mcp

# @vibeads/mcp

[![npm version](https://img.shields.io/npm/v/@vibeads/mcp.svg)](https://www.npmjs.com/package/@vibeads/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)

> **Talk to your Google Ads account from Claude Desktop, Cursor, or any MCP client.**
>
> Built for local service businesses — 34 categories with tuned keywords, CPC benchmarks and funnel templates.

The official [Model Context Protocol](https://modelcontextprotocol.io) server for [VibeAds](https://getvibeads.com). 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** — 26 home-service verticals plus 8 professional/lead-gen ones, each with its 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, 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

---

## Supported categories

**Local & home services (26):** 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 · 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

Any other category is accepted — it just falls back to generic defaults instead of the tuned knowledge base.

---

## Installation

### Step 1 — Get your API key

Sign in to your [VibeAds account](https://getvibeads.com) and generate an API key:

**[→ Generate API key](https://getvibeads.com/app/settings/mcp)**

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:

```json
{
  "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

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`

#### 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 each campaign's latest synced search terms, which cover the 7 days before that sync (configurable cost threshold) |
| `get_diagnostics` | Latest agent-optimize diagnostics with severity + recommended fix (up to 50) |

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 call is rate-limited per key, approved optimizations are measured afterwards (smaller changes roll back automatically 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 |
| `apply_strategy` | Turn a completed preview into a real draft campaign (ad groups, keywords, targeting, ad copy, extensions). Costs 6 credits + 3 per ad group for image generation. Draft only — not live, no ad money spent |
| `list_recommendations` | Pending optimization recommendations awaiting approval, with the session + recommendation IDs |
| `approve_recommendation` | Execute ONE diagnosed optimization. Approving closes its session and rejects the other recommendations in it |
| `request_publish` | Start the publish flow for a campaign that has ad groups — returns a human-approval URL because publishing spends real money |
| `check_approval` | Poll a publish approval: pending → approved → executing → executed (or rejected / expired / failed) |

**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` and returns an approval link.
5. You open the link in your browser, review the campaign + 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). Step 5 is the only point where **ad** money is committed, and it can only happen in a browser — the API key alone can never publish.

---

## 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 per key. Approved optimizations are measured afterwards, smaller changes roll back automatically if metrics worsen, 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