@vibeads/mcp

@vibeads/mcp

Talk to your Google Ads account from Claude Desktop, Cursor, or any MCP client.

Built for local service businesses — plumbers, HVAC, electricians, roofers, and 33 more categories.

The official Model Context Protocol server for VibeAds. Ask Claude questions like "which search terms are wasting my budget?" or "what's my account health score?" and get answers pulled from your live campaign data.

Unlike generic Google Ads MCP servers, this one is pre-tuned for local service businesses and rolls up 35+ diagnostic rules into a single 0-100 account health score across 6 dimensions. On Pro/Max plans it can also draft campaign strategies, execute guarded optimizations, and kick off publish flows — with a human always approving anything that spends money.

Features

• 🎯 Local-service-first — tuned for plumbers, HVAC, electricians, and 34 more categories
• 📊 Account Health Score 0-100 — weighted across 6 dimensions (Tracking, Keywords, Budget, Creative, Targeting, Performance)
• 🔍 Search term waste detection — finds every dollar burning on zero-conversion terms
• 💡 Diagnostic rollup — 35+ rules from VibeAds' optimization engine, ranked by severity
• ✍️ Write tools (Pro/Max) — draft strategies, approve optimizations, and start publish flows through the VibeAds gateway
• 🔒 Safe by design — read tools can't modify anything; write tools run inside VibeAds' safety guardrails, and publishing always requires a human to approve in the browser
• ⚡ No GAQL required — ask questions in natural language, get markdown answers

Installation

Step 1 — Get your API key

Sign in to your VibeAds account and generate an API key:

→ Generate API key

Keys start with vba_mcp_ and are scoped to your account only.

Step 2 — Configure your MCP client

Claude Desktop

Open your config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add this to the mcpServers block:

{
  "mcpServers": {
    "vibeads": {
      "command": "npx",
      "args": ["-y", "@vibeads/mcp"],
      "env": {
        "VIBEADS_API_KEY": "vba_mcp_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop. You should see the VibeAds tools appear in the 🔨 tool menu.

Cursor

• Open Settings → MCP
• Click Add Server
• Configure:
  • Name: vibeads
  • Command: npx -y @vibeads/mcp
  • Environment variables: VIBEADS_API_KEY=vba_mcp_YOUR_KEY_HERE

Cline / Claude Code / other MCP clients

Use the same config as Claude Desktop above. Most MCP clients follow the same schema.

Environment variables

Setup is one env var — every tool (read and write) runs through the secure server-side VibeAds gateway with your API key.

Variable	Required?	Purpose
VIBEADS_API_KEY	✅ Required	Your vba_mcp_... key. This is the only credential any tool needs.
VIBEADS_SUPABASE_URL	Optional	Override the VibeAds backend URL. Defaults to the production endpoint.

Usage

Once configured, you can ask Claude questions like:

📋 Campaign discovery

"Show me all my VibeAds campaigns"

"Which campaigns are paused?"

"Give me the 5 most recently created campaigns"

🔬 Deep dives

"Tell me everything about my plumber campaign in Austin"

"How did my HVAC campaign perform last week?"

"What's the CPA for campaign abc12345?"

📊 Account health

"What's my VibeAds account health score?"

"Which dimension is pulling my score down?"

"Give me the health score just for campaign xyz"

💸 Search term analysis

"What search terms are wasting my budget?"

"Show me the top 10 winning keywords from the last 30 days"

"How much am I wasting on terms with zero conversions?"

🩺 Diagnostics + recommendations

"What should I fix first?"

"Show me all critical diagnostics"

"What's wrong with my roofing campaign?"

Available tools

Read tools

Tool	Purpose
list_campaigns	Enumerate all campaigns with status, budget, category
get_campaign_details	Deep dive on one campaign: metrics, ad groups, targeting, landing pages, diagnostics
get_account_health_score	0-100 score + letter grade across 6 dimensions, optionally per-campaign
get_search_term_analysis	Wasted spend + winners from search terms report (configurable lookback + threshold)
get_diagnostics	Full list of active agent-optimize diagnostics with severity + recommended fix

The read tools are read-only — they cannot create, modify, pause, or delete anything in your Google Ads account. They run server-side through the VibeAds gateway and need only VIBEADS_API_KEY. Read tools work on any plan, free tier included.

Write tools (Pro/Max)

Write tools talk to the secure server-side VibeAds gateway and need only VIBEADS_API_KEY — no Supabase keys. Every action runs inside VibeAds' safety guardrails (blast-radius caps, rate limits, auto-rollback if metrics worsen), and publishing always requires a human approving in the browser — the API key alone can never spend money.

Tool	Purpose
generate_strategy	Draft a full campaign strategy (keywords, ad copy, 3+ ad groups) server-side. Costs 13 credits. Draft only — nothing is published, no money is spent
get_strategy_status	Poll a strategy job: status, phase, and drafted ad groups once complete
list_recommendations	Pending optimization recommendations awaiting approval, with the session + recommendation IDs
approve_recommendation	Execute ONE diagnosed optimization inside the safety guardrails; sibling recommendations stay pending
request_publish	Start the publish flow — returns a human-approval URL because publishing spends real money
check_approval	Poll a publish approval: pending → approved → executing → executed (or rejected / expired / failed)

The approval-link flow:

• The agent calls request_publish and shows you an approval link.
• You open the link in your browser and log in to VibeAds.
• You review the campaign + budget and click Approve (or Reject).
• The agent polls check_approval and continues once the campaign is live.

Security

• Read tools are read-only. They cannot mutate your campaigns, your Google Ads account, or your VibeAds settings.
• Write tools are guarded. Every write action runs server-side inside VibeAds' safety guardrails (blast-radius caps, rate limits, automatic rollback), and publishing always requires a human approving in the browser — the API key can never approve ad spend by itself.
• Keys are hashed with SHA-256 before storage. The full key is only shown once at creation.
• Revocable any time from https://getvibeads.com/app/settings/mcp.
• Usage is logged per-key: last-used timestamp and request count.
• Row-level isolation — each key is scoped to a single VibeAds user. Keys cannot see other users' data.
• Optional expiry — set expiration dates on keys for service accounts / temporary access.

For maximum security, rotate your API key whenever a device changes hands or an engagement ends.

Requirements

• Node.js ≥ 20 (for npx runtime)
• Active VibeAds account — free tier is sufficient to generate a key
• Pro or Max plan — required for the write tools (read tools work on any plan)
• At least one published campaign — diagnostics require synced data from Google Ads

How it compares

	VibeAds MCP	GoMarble MCP	Google Ads MCP (official)
Setup time	2 min	15 min	30 min
OAuth required	❌ (API key only)	✅	✅
GAQL knowledge required	❌	✅	✅
Local service tuning	✅	❌	❌
Account health score	✅ 6 dimensions	❌	❌
Pre-built diagnostics	✅ 35+ rules	❌	❌
Multi-account	✅	✅	✅
Guarded write actions	✅ human-approved publish	❌	❌

When to use VibeAds MCP: You run a local service business (or manage ads for one) and want pre-tuned insights without learning GAQL.

When to use GoMarble / Google Ads MCP: You need to run custom GAQL queries or work with non-service-business campaigns (e-commerce, B2B SaaS, etc.).

The three can coexist — install whichever ones fit your workflow.

Troubleshooting

"Authentication failed"

• Make sure your key starts with vba_mcp_
• Generate a new key at https://getvibeads.com/app/settings/mcp
• Check that the key hasn't been revoked or expired

"No diagnostic data yet"

Diagnostics are generated every 6 hours by the VibeAds agent. If you just published a campaign, wait 6-12 hours for the first run.

"No search term data found"

Search term sync runs every 6 hours. For new campaigns, allow 24-48 hours for meaningful data to accumulate.

MCP client can't find the server

Make sure you have Node.js 20+ installed: node --version. Claude Desktop and Cursor both shell out to npx, so Node must be in your PATH.

Contributing

This is an open-source MIT package. Issues and PRs welcome at: https://github.com/vibeads/mcp/issues

License

MIT © VibeAds