Quick Start

1. Get Credentials

You need a Google Ads API developer token and OAuth client credentials.

1. Download your OAuth client JSON from Google Cloud Console
2. Set environment variables:

export GOOGLE_ADS_DEVELOPER_TOKEN=your-token
export GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json

3. Run the setup helper to authorize:

npx mcp-gads setup

This opens your browser, completes OAuth, and saves a refresh token.

2. Add to Claude Code

claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- npx -y mcp-gads@latest

That's it. Restart Claude Code and the tools are available. Every session runs the latest version automatically.

Also works with bunx mcp-gads@latest if you have Bun. Requires Node 18+ when running via npx.

If your environment blocks npm registry access at runtime, install once and run the published binary name directly:

npm i -g mcp-gads@latest
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- mcp-gads

Download a pre-built binary from Releases:

| Platform | File | |----------|------| | macOS (Apple Silicon) | mcp-gads-darwin-arm64 | | macOS (Intel) | mcp-gads-darwin-x64 | | Linux | mcp-gads-linux-x64 | | Windows | mcp-gads-windows-x64.exe |

macOS / Linux:

curl -Lo mcp-gads https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-darwin-arm64
chmod +x mcp-gads
sudo mv mcp-gads /usr/local/bin/
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- /usr/local/bin/mcp-gads

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\mcp-gads.exe"
claude mcp add google-ads --scope user --transport stdio -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token -e GOOGLE_ADS_CREDENTIALS_PATH=C:\path\to\credentials.json -- "%LOCALAPPDATA%\mcp-gads.exe"

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "mcp-gads@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-ads": {
      "command": "/usr/local/bin/mcp-gads",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-ads": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\mcp-gads.exe",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "C:\\path\\to\\credentials.json"
      }
    }
  }
}

Tools (39)

Account Management

| Tool | Description | |------|-------------| | list_accounts | List all accessible Google Ads accounts | | get_account_currency | Get the currency code for an account | | get_account_hierarchy | Get MCC account tree (manager -> client) |

Queries

| Tool | Description | |------|-------------| | execute_gaql_query | Run any GAQL query (table output) | | run_gaql | Run GAQL with format options (table/json/csv) | | get_gaql_help | GAQL reference guide with syntax, resources, and examples | | list_resources | List valid GAQL FROM clause resources |

Campaigns

| Tool | Description | |------|-------------| | get_campaign_performance | Campaign metrics (impressions, clicks, cost, conversions) | | get_budget_utilization | Budget amounts vs actual spend |

Ads

| Tool | Description | |------|-------------| | get_ad_performance | Ad-level performance metrics | | get_ad_creatives | RSA headlines, descriptions, final URLs |

Assets

| Tool | Description | |------|-------------| | get_image_assets | List image assets with URLs and dimensions | | download_image_asset | Download a specific image asset to disk | | get_asset_usage | Find where assets are used (campaigns, ad groups) | | analyze_image_assets | Image asset performance with metrics |

Keywords

| Tool | Description | |------|-------------| | generate_keyword_ideas | Keyword Planner suggestions from seed keywords | | get_keyword_volumes | Historical search volume for specific keywords | | get_quality_scores | Quality scores with component breakdown | | get_search_terms | Actual search queries triggering your ads |

Geographic & Device

| Tool | Description | |------|-------------| | get_geographic_performance | Performance by location | | get_device_performance | Performance by device type |

Insights

| Tool | Description | |------|-------------| | get_recommendations | Google's AI optimization suggestions | | get_change_history | Recent account changes |

Extended Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_EXTENDED_TOOLS=true:

| Tool | Description | |------|-------------| | get_ad_group_performance | Ad group metrics with optional campaign filter | | get_conversion_actions | Conversion actions with settings and performance | | get_account_summary | Quick dashboard: totals + top 5 campaigns | | get_impression_share | Competitive position: impression share and lost IS | | get_ad_schedule_performance | Performance by hour or day of week | | get_audience_performance | Demographics: age range and gender breakdowns | | get_landing_page_performance | Landing page URLs with metrics | | get_placement_performance | Display/PMax placement details | | get_asset_group_performance | PMax asset group metrics and ad strength | | get_video_performance | YouTube/video view rates and quartile completion | | get_labels | Labels and their campaign/ad group assignments |

Write Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_MUTATIONS=true:

| Tool | Description | |------|-------------| | update_campaign_status | Pause/enable a campaign | | update_ad_group_status | Pause/enable an ad group | | update_ad_status | Pause/enable an ad | | update_campaign_budget | Change daily budget amount | | add_negative_keywords | Add negative keywords to a campaign |

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GOOGLE_ADS_DEVELOPER_TOKEN | Yes | — | API developer token | | GOOGLE_ADS_CREDENTIALS_PATH | Yes | — | Path to OAuth client JSON | | GOOGLE_ADS_AUTH_TYPE | No | oauth | oauth or service_account | | GOOGLE_ADS_CUSTOMER_ID | No | — | Default customer ID (skips passing it per tool) | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | No | — | MCC manager account ID | | GOOGLE_ADS_IMPERSONATION_EMAIL | No | — | Service account impersonation email | | GOOGLE_ADS_ENABLE_MUTATIONS | No | false | Enable write tools | | GOOGLE_ADS_ENABLE_EXTENDED_TOOLS | No | false | Enable extended read tools (11 extra) | | GOOGLE_ADS_ENV_FILE | No | .env | Path to .env file (loaded if present, never overrides existing env) | | GOOGLE_ADS_API_VERSION | No | v23 | Google Ads API version |

Updates

Using npx @latest (recommended): You always get the latest version — no manual updates needed.

Using a binary: The server checks for new releases on startup and logs to stderr if outdated:

[mcp-gads] v0.2.0 available (current: v0.1.0). Download: https://github.com/pijusz/mcp-gads/releases/latest

Check your installed version:

mcp-gads --version

To update, download the new binary and replace the old one.

Development

Requires Bun.

git clone https://github.com/pijusz/mcp-gads.git
cd mcp-gads
bun install
bun test           # tests
bun run build      # standalone binary
bun run inspect    # MCP Inspector
bun run check      # biome format + lint

License

MIT