Google Ads

MCP Google Ads Server

An MCP (Model Context Protocol) server for the Google Ads API with built-in safeguards for review before changes go live. Production-proven with MCC (Manager Account) support, 36 tools for campaign management, reporting, and optimization. v1.2.0 adds Demand Gen campaign creation end-to-end.

Features

• MCC Support: Works with Manager accounts and multiple client accounts
• Auto-Context: Detects which client account based on your working directory
• Safe by Default: All new items created in PAUSED state
• Approval Workflow: Enable items only after manual review
• Validation: Validates ads before creating to catch errors early
• Resilience: Circuit breakers, retry with backoff, and timeout handling (cockatiel)
• Structured Logging: Pino-based logging with build fingerprinting

Setup

1. Google Ads API Access

You need:

• A Google Ads Developer Token (apply at Google Ads API Center)
• OAuth credentials (Client ID & Secret from Google Cloud Console)
• A Refresh Token for your MCC account

Getting OAuth Credentials

1. Go to Google Cloud Console
2. Create a project or select existing
3. Enable the Google Ads API
4. Go to Credentials → Create Credentials → OAuth Client ID
5. Choose Desktop App
6. Download the JSON (contains client_id and client_secret)

Getting a Refresh Token

Bring your own OAuth client (the client_id / client_secret from the step above) and run the bundled helper. It runs Google's installed-app loopback flow with PKCE (S256) and prints your refresh token. It reads nothing from your home directory and needs no shared OAuth keyfile.

export GOOGLE_ADS_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"export GOOGLE_ADS_CLIENT_SECRET="YOUR_CLIENT_SECRET"node get-refresh-token.cjs

Your browser opens for Google sign-in; approve as the Google account that owns the Ads data. On success the helper prints one line to stdout:

GOOGLE_ADS_REFRESH_TOKEN=1//0a...

Set that value in your environment (or config.json, below). The OAuth scope requested is read from config.json (oauth.scope), falling back to config.example.json, so the helper and the running server always request the same scope. This MCP requests only the minimum scope it needs: https://www.googleapis.com/auth/adwords.

Do not run this with stdout redirected to a shared log file — the refresh token is printed to stdout by design.

Note: GOOGLE_ADS_DEVELOPER_TOKEN is a separate Google Ads API credential, not an OAuth scope — set it independently (see Environment Variables below).

2. Install

npm install mcp-google-ads

Or clone and build from source:

git clone https://github.com/mharnett/mcp-google-ads.gitcd mcp-google-adsnpm installnpm run build

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

3. Configure

cp config.example.json config.json

Edit config.json with your credentials:

{  "oauth": {    "scope": "https://www.googleapis.com/auth/adwords"  },  "google_ads": {    "developer_token": "YOUR_DEVELOPER_TOKEN",    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",    "client_secret": "YOUR_CLIENT_SECRET",    "refresh_token": "YOUR_REFRESH_TOKEN",    "mcc_customer_id": "123-456-7890"  },  "clients": {    "my-client": {      "customer_id": "111-222-3333",      "name": "My Client",      "folder": "/path/to/client/workspace"    },    "another-client": {      "customer_id": "444-555-6666",      "name": "Another Client",      "folder": "/path/to/another/workspace"    }  },  "defaults": {    "create_paused": true,    "label_prefix": "claude-",    "require_approval_for_enable": true  }}

Environment Variables

Alternatively, set credentials via environment variables (these override config.json):

Always-loaded tools

Clients that defer tool schemas behind a tool-search step only load a tool once it is searched for. Naming tools in GOOGLE_ADS_MCP_ALWAYS_LOAD stamps them with _meta: {"anthropic/alwaysLoad": true} in tools/list, so those tools are offered directly. Names that match no tool are ignored, and the marker never exposes a tool that read-only mode hides.

Read-only by default

The server ships read-only. Mutating tools (anything that creates, updates, pauses, enables, removes, links, or applies) are hidden from the tool list until you set GOOGLE_ADS_MCP_WRITE=true in the MCP server environment. If a write tool is somehow invoked without that flag, the server returns a clear error pointing at the env var.

This is deliberate: a casual chat message like "activate the Fundraising campaign" should not move live ad spend without an explicit opt-in.

4. Add to Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project settings):

{  "mcpServers": {    "google-ads": {      "command": "node",      "args": ["node_modules/mcp-google-ads/dist/index.js"]    }  }}

Or if installed from source:

{  "mcpServers": {    "google-ads": {      "command": "node",      "args": ["/path/to/mcp-google-ads/dist/index.js"]    }  }}

Restart Claude Code.

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Usage

Workflow

1. cd into client folder → auto-detects account context2. Ask Claude to create campaigns/ads → all created PAUSED3. Review in Google Ads UI or Editor4. Tell Claude to enable approved items5. Claude enables (requires your approval prompt)

Available Tools (36)

Context & Discovery

Campaign Management

Tracking & URLs

Negative Keywords

Performance & Reporting

Advanced

Example Commands

# Check which account you're working with"What Google Ads account am I connected to?"
# List campaigns"Show me all campaigns in this account"
# Create a new campaign"Create a Search campaign for brand terms with $50/day budget"
# Check what's pending review"What changes are pending my review?"
# After reviewing in Google Ads UI"Enable the approved ads in the Brand campaign"
# Performance analysis"Show me keyword performance for the last 30 days, sorted by cost"
# Run custom GAQL"Run a GAQL query to get all ad groups with CTR below 2%"

Example: Create a Demand Gen Campaign End-to-End

# 1. Campaign: $75/day, DEMAND_GEN channel, MAXIMIZE_CONVERSIONS default,#    targeting Alaska (21134) + Maine (21141) in Englishgoogle_ads_create_campaign({  name: "DG - Spring Promo",  daily_budget: 75,  channel_type: "DEMAND_GEN",  geo_target_ids: ["21134", "21141"],  start_date: "2026-05-01",  end_date: "2026-06-30"})# → campaign_id: 555123
# 2. Ad group: DEMAND_GEN_MULTI_ASSET_AD_GROUPgoogle_ads_create_ad_group({  campaign_id: "555123",  name: "DG AG 1",  type: "DEMAND_GEN_MULTI_ASSET_AD_GROUP"})# → ad_group_id: 555456
# 3. Image assets (PNG/JPG/GIF, ≥600×314, ≤5MB). Returns {asset_id, ...}google_ads_create_image_asset({ name: "hero-landscape", file_path: "/abs/path/hero.png" })# → asset_id: 42001google_ads_create_image_asset({ name: "hero-square",    file_path: "/abs/path/square.png" })# → asset_id: 42002google_ads_create_image_asset({ name: "logo",           file_path: "/abs/path/logo.png" })# → asset_id: 42003
# 4. Demand Gen multi-asset ad (PAUSED). Validates char + count caps first.google_ads_create_demand_gen_multi_asset_ad({  ad_group_id: "555456",  final_urls: ["https://example.com/spring"],  business_name: "Example Org",  call_to_action: "LEARN_MORE",  marketing_image_asset_ids: ["42001"],          // 1.91:1 landscape, ≥1 required  square_marketing_image_asset_ids: ["42002"],   // 1:1 optional  logo_image_asset_ids: ["42003"],               // logo optional  headlines: ["Spring Sale Now On", "Save 20% Today"],     // max 5, ≤40 chars each  long_headlines: ["A longer pitch under ninety characters."], // max 5, ≤90 chars  descriptions: ["Shop the latest looks.", "Free returns."]   // max 5, ≤90 chars each})# → resource_name: customers/.../adGroupAds/555456~67890000

After all four calls the campaign, ad group, and ad all live in your account in PAUSED state and are labeled Claude-MM-DD-YY. Review in the Google Ads UI, then enable via google_ads_enable_items.

Safety Features

1. Everything starts PAUSED — Nothing goes live until you explicitly enable it
2. Label tracking — All Claude-created items get a claude-pending label
3. Validation — Ads are validated before creation (headline/description lengths, etc.)
4. Approval prompts — The enable_items tool requires explicit approval in Claude Code
5. Client isolation — Working directory determines which account, preventing cross-client mistakes
6. Magnitude ceilings — update_campaign_budget refuses a change larger than ±20% of the current budget unless confirm_large_change: true and a non-empty reason are passed; update_campaign_bidding does the same for targets. Every override is logged (see GOOGLE_ADS_MCP_OVERRIDE_LOG)
7. expected_old — Update tools accept an optional expected_old: the value you believe you are overwriting. If the live value differs, the tool refuses, returns current vs expected and makes no write

Adding New Clients

Edit config.json to add clients. Map each client to a working directory:

{  "clients": {    "client-slug": {      "customer_id": "123-456-7890",      "name": "Client Name",      "folder": "/path/to/client/workspace"    }  }}

No server restart needed — config is read on each request.

Troubleshooting

"No client found for working directory"

• Make sure you're in a folder that matches one of your clients entries
• Check that the folder path in config.json matches exactly

"Developer token not approved"

• New developer tokens need approval from Google
• Use a test account while waiting for approval

"Authentication failed"

• Refresh token may be expired — regenerate it
• Check that client_id and client_secret are correct

License

MIT — see LICENSE for details.