io.github.pijusz/mcp-gads

Official

by pijusz · TypeScript

Google Ads MCP server — query campaigns, keywords, assets & more via natural language

Query Google Ads campaigns, keywords, and assets using natural language.

<img src="logo.svg" alt="mcp-gads" width="280" /> Google Ads MCP server — query campaigns, keywords, assets & more via natural language. Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.

Quick Start

1. Get Credentials

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

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

bash

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

Run the setup helper to authorize:

bash

npx mcp-gads setup

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

2. Add to Claude Code

bash

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:

bash

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:

bash

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):

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:

bash

npm i -g mcp-gads

toml

[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>

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

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

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

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

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

</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

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:

code

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

Check your installed version:

bash

mcp-gads --version

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

Development

Requires Bun.

bash

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

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-gads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-gads@0.5.4"
      ]
    }
  }
}