io.github.pijusz/mcp-gads
Google Ads MCP server β query campaigns, keywords, assets & more via natural language
Ask AI about io.github.pijusz/mcp-gads
Powered by Claude Β· Grounded in docs
I know everything about io.github.pijusz/mcp-gads. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
export GOOGLE_ADS_DEVELOPER_TOKEN=your-token
export GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json
- 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@latestif you have Bun. Requires Node 18+ when running vianpx.
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
Alternative: standalone binary
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"
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 -ywithout raising the timeout. Codex's defaultstartup_timeout_secis 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, addstartup_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:
Using npx (auto-updates)
{
"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"
}
}
}
}
Using binary (macOS / Linux)
{
"mcpServers": {
"google-ads": {
"command": "/usr/local/bin/mcp-gads",
"env": {
"GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
"GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
}
}
}
}
Using binary (Windows)
{
"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
