Feature	Google Official	Others	This
Tools	2	8	49
Tool Annotations	❌	❌	✅
Lazy Loading	❌	❌	✅
MCP Apps (Rich UI)	❌	❌	7 apps
Safety Guardrails	❌	❌	✅
Keyword Planner	❌	❌	✅
GAQL Query Builder	❌	❌	✅
Conversion Tracking	❌	❌	✅
Ad Management	❌	❌	✅

Quick Start

1. Install

npx @busybee/google-ads-mcp

2. Configure

Set credentials via environment variables:

# Option A: Inline JSON (simple)
export GOOGLE_ADS_CONFIG='{"client_id":"YOUR_ID","client_secret":"YOUR_SECRET","developer_token":"YOUR_TOKEN","refresh_token":"YOUR_REFRESH","login_customer_id":"YOUR_MANAGER_ID"}'
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

# Option B: Individual env vars
export GOOGLE_ADS_CLIENT_ID="YOUR_ID"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_SECRET"
export GOOGLE_ADS_DEVELOPER_TOKEN="YOUR_TOKEN"
export GOOGLE_ADS_REFRESH_TOKEN="YOUR_REFRESH"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="YOUR_MANAGER_ID"  # optional
export GOOGLE_ADS_CUSTOMER_ID="1234567890"              # optional default

3. Add to MCP Client

Claude Desktop / Cursor / Gemini CLI:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["@busybee/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_CONFIG": "{...}",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Tool Categories

Always Loaded (24 core tools)

Account Management (5) — list accounts, info, hierarchy, billing, budgets
Campaign Management (8) — list, get, create, update, pause, enable, remove, budget
Reporting (7) — performance summary, campaign/ad group/keyword/geo/device metrics, search terms
Advanced (4) — raw GAQL queries, export CSV/JSON, change history, labels

Lazy Loaded (25 tools, load on demand)

Ad Groups (6) — list, get, create, update, pause, enable
Ads (5) — list, get, create RSA, update, pause
Keywords (6) — list, add, remove, keyword ideas, metrics, negatives
Bidding (4) — strategies, bid recommendations, update bids, optimization recs
Conversions (4) — list actions, conversion metrics, create actions, upload offline

Use load_tools_category to load additional categories on demand.

MCP Apps (Rich UI)

7 interactive HTML dashboard components rendered via structuredContent:

Campaign Dashboard — Card grid with status pills, metrics, budget bars
Performance Overview — KPI cards, 7-day spend chart, top campaigns
Campaign Detail — Deep-dive with settings, budget, ad groups table
Keyword Analyzer — Quality score visualization, match type badges
Search Terms Report — Triggering terms with suggested actions
Recommendations — Google's optimization recs with impact scoring
Budget Optimizer — Allocation bars, over/underspend indicators

Tool Annotations

Every tool is annotated with MCP hints:

readOnlyHint — safe to call, no side effects
destructiveHint — modifies account data
idempotentHint — safe to retry
openWorldHint — queries external data sources

Safety Guardrails

Campaigns created in PAUSED state by default
Budget updates show before → after comparison
Destructive operations clearly marked with ⚠️
GAQL query runner blocks mutation keywords
Remove operations warn about irreversibility

Architecture

src/
├── index.ts              # MCP server entry point
├── auth.ts               # OAuth2 token management
├── client.ts             # Google Ads API v21 REST client
├── types.ts              # Shared types + formatting
├── tools/
│   ├── index.ts          # Tool registry + lazy loading
│   ├── accounts.ts       # 5 account tools
│   ├── campaigns.ts      # 8 campaign tools
│   ├── ad-groups.ts      # 6 ad group tools
│   ├── ads.ts            # 5 ad tools
│   ├── keywords.ts       # 6 keyword tools
│   ├── reporting.ts      # 7 reporting tools
│   ├── bidding.ts        # 4 bidding tools
│   ├── conversions.ts    # 4 conversion tools
│   └── advanced.ts       # 4 utility tools
└── apps/
    ├── index.ts           # App registry
    ├── theme.ts           # Shared dark theme CSS
    ├── campaign-dashboard.ts
    ├── performance-overview.ts
    ├── campaign-detail.ts
    ├── keyword-analyzer.ts
    ├── search-terms.ts
    ├── recommendations.ts
    └── budget-optimizer.ts

License

MIT