mcp-gads

<p align="center"> <img src="logo.svg" alt="mcp-gads" width="280" /> </p>

<p align="center"> Google Ads MCP server — query campaigns, keywords, assets & more via natural language. <br/> Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client. </p>

---

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

<details> <summary>Alternative: standalone binary</summary>

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"

</details>

ChatGPT Codex

Codex uses TOML, not JSON. Install once, then add to ~/.codex/config.toml:

npm i -g mcp-gads

[mcp_servers.gads]
command = "mcp-gads"

[mcp_servers.gads.env]
GOOGLE_ADS_DEVELOPER_TOKEN = "your-token"
GOOGLE_ADS_CREDENTIALS_PATH = "/absolute/path/to/credentials.json"

Three gotchas that cause silent failures on Codex:

• Don't use npx -y without raising the timeout. Codex's default startup_timeout_sec is 10s, which is too short for npx's first-run download. A global install (above) or the prebuilt binary sidesteps this entirely. If you must use npx, add startup_timeout_sec = 30.
• Env vars must go under [mcp_servers.gads.env]. Codex does not inherit the parent shell environment into stdio servers — exporting vars in your shell won't reach the server.
• Use absolute paths for GOOGLE_ADS_CREDENTIALS_PATH. Codex spawns the server with its own cwd, so relative paths silently miss.

On Windows some Codex versions use startup_timeout_ms = 20000 instead of _sec.

Claude Desktop

Add to your claude_desktop_config.json:

<details> <summary>Using npx (auto-updates)</summary>

{
  "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"
      }
    }
  }
}

</details>

<details> <summary>Using binary (macOS / Linux)</summary>

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

</details>

<details> <summary>Using binary (Windows)</summary>

{
  "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"
      }
    }
  }
}

</details>

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