Vibeads MCP README

@vibeads/mcp

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

Built for local service businesses: 35 categories, 32 of them with tuned keywords, CPC benchmarks and funnel templates.

The official Model Context Protocol server for VibeAds. Ask your assistant 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, apply guarded optimizations, edit keywords, bids and budgets, add ad groups, and publish, with you confirming anything that spends money.

There are two ways to connect, and both reach the same 29 tools:

• Sign in (OAuth). Add the hosted server, https://getvibeads.com/api/mcp, in ChatGPT, Claude, Meta AI or Claude Code and sign in to VibeAds when it asks. No key and nothing to install.
• API key. For Cursor, Cline, Windsurf and any client that can't sign in: create a vba_mcp_ key and use this npm package, or send the key to the hosted server in a header.

Features

• 🎯 Local-service-first: 27 home-service verticals plus 8 professional/lead-gen ones; 32 of them have their own keyword seeds, CPC benchmarks, audience segments and funnel template
• 📊 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, apply optimizations, edit keywords, bids and budgets, and publish through the VibeAds gateway
• 🔐 Sign in or use a key: OAuth sign-in for assistants that support it, a revocable API key for everything else. Your Google login never reaches the assistant
• 🔒 Safe by design: read tools can't modify anything; write tools run inside VibeAds' safety guardrails, and nothing spends money without you confirming it
• ⚡ No GAQL required: ask questions in natural language, get markdown answers

Supported categories

Local & home services (27): plumber · HVAC · electrician · roofer · cleaner · landscaper · pest control · painter · handyman · locksmith · garage door · appliance repair · tree service · fencing · windows & doors · carpet & flooring · waterproofing · pressure washing · air duct & dryer vent cleaning · commercial cleaning & janitorial · pool services · junk removal · movers · auto repair · Christmas lighting · dentist · lawyer

Professional & lead-gen (8): real estate · insurance · financial services · education · healthcare · consulting · SaaS · B2B services

Consulting, SaaS and B2B services use generic defaults, and so does any other category you pass, instead of a tuned knowledge base.

Connect

An approval link only works in your own signed-in VibeAds session, so neither a key nor a connected app can approve it.

Option A: sign in (no key, nothing to install)

ChatGPT, Claude and Meta AI

Add the server address as a custom connector (Claude, Meta AI) or a custom MCP server (ChatGPT), and sign in to VibeAds when the assistant asks:

https://getvibeads.com/api/mcp

Step-by-step instructions for each one: Connect ChatGPT, Claude or Meta AI. VibeAds emails you when an app is connected to your account.

Claude Code

Add the server with a fixed callback port, then open /mcp in Claude Code, choose VibeAds and sign in in your browser:

claude mcp add --transport http --callback-port 31790 vibeads https://getvibeads.com/api/mcp

Any free port works; 31790 is an example. Keep it fixed: VibeAds checks the return address exactly, so a later sign-in on a different port is refused (run claude mcp remove vibeads and add it again). VibeAds' sign-in page calls Claude Code "An app on this computer": allow it only if you just started connecting from Claude Code.

Signed-in apps are listed in Settings, Connected apps, where you can disconnect them and set the daily budget assistants may publish up to.

Option B: API key

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_, are shown once, and are scoped to your account only. Make one per client or machine, so you can revoke one without touching the others.

Step 2: configure your MCP client

This package runs on your computer and forwards every call to VibeAds with your key. It always uses an API key; to sign in instead, use Option A.

Claude Desktop

Open your config file:

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. (Claude Desktop can also sign in instead, through a custom connector: see Option A.)

Cursor

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

Claude Code

claude mcp add vibeads -e VIBEADS_API_KEY=vba_mcp_YOUR_KEY_HERE -- npx -y @vibeads/mcp

Cline and other MCP clients

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

npx -y @vibeads/mcp --init prints ready-to-paste configs for each client.

Or: the hosted server with your key

Nothing to install: give the client the hosted address and send the key in an x-vibeads-api-key header. In Claude Code:

claude mcp add --transport http vibeads https://getvibeads.com/api/mcp --header "x-vibeads-api-key: vba_mcp_YOUR_KEY_HERE"

The key also works as Authorization: Bearer vba_mcp_.... A client that can't send headers can put it in the address (https://getvibeads.com/api/mcp?key=vba_mcp_...); that address then works like a password, so prefer a header or signing in. Guides for Cursor, OpenAI Codex, Gemini CLI and VS Code with GitHub Copilot.

Environment variables (this package)

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

Usage

Once connected, you can ask your assistant 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?"

📈 Reports for any period

"Compare September with August for my Austin plumbing campaign"

"Spend by device across my whole account last month"

"Which keywords spent the most in the last 90 days?"

🔎 Keyword research

"How many people search for drain cleaning in Austin, TX?"

"Find keyword ideas from my services page for Round Rock and Pflugerville"

🧾 Audit a whole Google Ads account

Works right after you connect Google Ads, before anything is imported:

"Where is my Google Ads budget being wasted?"

"Audit my Google Ads account"

📊 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

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, the same whether you signed in or use a key. Read tools work on any plan, free tier included, except research_keywords, which needs Pro or Max.

Write tools (Pro/Max)

Write tools run on the server-side VibeAds gateway, with a sign-in or an API key and nothing else (no Supabase or Google keys). Every call is rate-limited, approved optimizations are measured afterwards (smaller changes roll back automatically if metrics worsen), and nothing that spends money happens without you confirming it: an API key, or Claude Code signed in, gets an approval link you open in VibeAds; ChatGPT, Claude and Meta AI publish only within the daily limit you allow assistants, after you confirm the budget in the chat.

Every keyword, bid, budget and restart change is listed on the campaign's Optimize tab in VibeAds, where it can be undone. VibeAds never rolls these back by itself. An assistant can make 20 changes to a campaign a day.

From idea to live campaign:

1. generate_strategy drafts the strategy server-side and returns a jobId. Nothing exists in Google Ads yet.
2. get_strategy_status polls that job until it reports completed.
3. apply_strategy turns the finished preview into a real draft campaign and returns a campaignId. Still not live, still spending nothing.
4. request_publish takes that campaignId. With an API key or Claude Code it returns an approval link.
5. You open the link in your browser, signed in to VibeAds, review the campaign and its budget, and click Approve (or Reject).
6. check_approval reports the approval and then the publish job; the campaign is live once that job completes.

Steps 1–3 create rows only in VibeAds and spend VibeAds credits (13 for step 1; 6 + 3 per ad group for step 3). With an API key, step 5 is the only point where ad money is committed, and it can only happen in your browser: the key alone can never publish, so a leaked key still cannot spend.

ChatGPT, Claude and Meta AI, connected by signing in, skip the link for a Search campaign whose daily budget is within the limit you allow assistants ($100 a day unless you change it or turn it off, in VibeAds Settings under Connected apps): in step 4 the assistant tells you the daily budget, and publishes only after you confirm it in the chat. VibeAds emails you when the campaign is live. A bigger campaign gets the approval link.

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 through the VibeAds gateway, rate-limited to 60 calls an hour. Approved optimizations are measured afterwards, and smaller changes roll back automatically if metrics worsen. Every keyword, bid, budget and restart change an assistant makes is listed on the campaign's Optimize tab in VibeAds, where you can undo it.
• Spending needs you. An approval link only works in your own signed-in VibeAds session, so neither a key nor a connected app can approve one. An API key, or Claude Code signed in, can never publish, restart a campaign or raise a budget by itself.
• Your Google login stays with VibeAds. Google Ads connects to VibeAds once, through Google's own sign-in. A key or a signed-in app only ever reaches VibeAds; your Google tokens never reach the assistant or your computer.

Signing in (OAuth)

• OAuth 2.1 authorization code with PKCE. VibeAds' sign-in page shows which app is asking and what it may do, and you press Allow access.
• Outside these tools, VibeAds refuses a signed-in app anything that changes your account, and never lets it see your Google Ads login.
• VibeAds emails you when an app is connected to your account.
• Disconnect any app in Settings, Connected apps; it is signed out at once.

API keys

• Keys are hashed with SHA-256 before storage. The full key is only shown once at creation.
• Revocable any time from Settings, MCP Server Keys.
• Usage is logged per key: last-used date and request count.
• Each key is scoped to a single VibeAds user and cannot see other users' data.

For maximum security, revoke and replace an API key whenever a device changes hands or an engagement ends.

Requirements

• Active VibeAds account: sign-in and keys work on every plan, the free plan included
• Pro or Max plan: needed for the write tools (read tools work on any plan)
• Google Ads connected to VibeAds: for live numbers, importing and publishing. Connect it in VibeAds Settings, or from the link the assistant gives you when it needs it
• At least one published or imported campaign: diagnostics need synced data from Google Ads
• Node.js ≥ 20: only for this npm package (npx runs it); signing in or using the hosted server needs nothing installed

How it compares

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

"API key is invalid" or "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

"Missing VibeAds API key" (hosted server with a key)

The header name must be exactly x-vibeads-api-key, and the key must start with vba_mcp_. Or remove the header and sign in instead.

The assistant asks you to sign in again, or says it isn't connected

The app was disconnected in Settings, Connected apps, or its sign-in ended. Connect it again from the assistant (ChatGPT: Settings, Plugins, VibeAds; Claude: Customize, Connectors; Claude Code: /mcp) and sign in.

Claude Code: the sign-in is refused

Claude Code was added without a fixed callback port, or with a different one. Run claude mcp remove vibeads, add it again with --callback-port (see Option A), and sign in from /mcp.

"No optimizer diagnoses yet"

Diagnostics are generated every 12 hours by the VibeAds agent, once Google Ads performance has synced. If you just published a campaign, allow up to a day 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 (npm package)

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