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.git
cd mcp-google-ads
npm install
npm 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):

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 context
2. Ask Claude to create campaigns/ads → all created PAUSED
3. Review in Google Ads UI or Editor
4. Tell Claude to enable approved items
5. 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