Google Ads MCP Server
This skill configures the google-ads-mcp server for live Google Ads API access through Claude Code, Claude Desktop, Cursor, or any MCP client.
Quick Setup
1. Install
pip install git+https://github.com/itallstartedwithaidea/google-ads-mcp.git2. Configure Credentials
Create a .env file or set environment variables:
GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_CLIENT_ID=your-oauth-client-id
GOOGLE_ADS_CLIENT_SECRET=your-oauth-client-secret
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890Or point to an existing google-ads.yaml:
GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-78903. Run
python -m ads_mcp.serverClaude Code Configuration
Place .mcp.json in your project root:
{
"mcpServers": {
"google-ads": {
"type": "stdio",
"command": "python",
"args": ["-m", "ads_mcp.server"],
"env": {
"GOOGLE_ADS_CREDENTIALS": "${GOOGLE_ADS_CREDENTIALS}",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "${GOOGLE_ADS_LOGIN_CUSTOMER_ID}"
}
}
}
}Claude Code auto-discovers .mcp.json and loads the server on startup.
Claude Desktop Configuration
Add to claude_desktop_config.json:
{
"mcpServers": {
"google-ads": {
"command": "python",
"args": ["-m", "ads_mcp.server"],
"env": {
"GOOGLE_ADS_CREDENTIALS": "/path/to/google-ads.yaml",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "123-456-7890"
}
}
}
}Available Tools (29)
Read Tools (9)
| Tool | Description |
|---|---|
list_accessible_customers | List all accessible customer accounts |
list_accounts | List accounts under an MCC with details |
execute_gaql | Run custom GAQL queries |
get_campaign_performance | Campaign metrics with date range |
get_keyword_performance | Keyword metrics and quality scores |
get_search_terms | Search term report with wasted spend |
get_ad_performance | Ad creative performance |
get_account_budget_summary | Budget utilization analysis |
generate_keyword_ideas | Keyword Planner search volume and CPC |
Audit Tools (7)
| Tool | Description |
|---|---|
get_auction_insights | Competitive auction data |
get_change_history | Recent account changes |
get_device_performance | Performance by device type |
get_geo_performance | Performance by location |
get_recommendations | Google's optimization suggestions |
get_pmax_performance | Performance Max campaign data |
get_impression_share | Impression share and lost opportunity |
Write Tools (11) — dry-run by default
| Tool | Description |
|---|---|
update_campaign_budget | Change daily budget |
update_campaign_status | Pause or enable a campaign |
update_ad_group_status | Pause or enable an ad group |
update_keyword_bid | Change keyword CPC bid |
add_keywords | Add keywords to an ad group |
add_negative_keywords | Add negative keywords |
remove_negative_keyword | Remove a negative keyword |
create_campaign | Create a new campaign (paused) |
create_ad_group | Create a new ad group |
switch_bidding_strategy | Change bidding strategy |
generic_mutate | Raw Google Ads API mutation |
All write tools use confirm=False by default (dry-run preview). Pass confirm=True only after reviewing the preview.
Doc Tools (2)
| Tool | Description |
|---|---|
get_gaql_reference | GAQL syntax and field reference |
get_workflow_guide | Step-by-step workflow instructions |
Credential Sources
| Value | Where to Get It |
|---|---|
| Developer Token | ads.google.com → Tools & Settings → API Center |
| Client ID | console.cloud.google.com → Credentials |
| Client Secret | console.cloud.google.com → Credentials |
| Refresh Token | OAuth Playground or google-ads Python auth helper |
| Login Customer ID | Your MCC account ID (top of Google Ads UI) |
Troubleshooting
| Problem | Fix |
|---|---|
UNAUTHENTICATED | Refresh token expired — regenerate via OAuth Playground |
PERMISSION_DENIED | Account not accessible under your MCC |
DEVELOPER_TOKEN_NOT_APPROVED | Apply for Basic Access at ads.google.com → API Center |
| Rate limit exceeded | Basic Access: 15K ops/day. Use LIMIT clauses and filters. |
Related
- google-ads-mcp repo — Full source code
- google-ads-api-agent — Python agent with 28 tools
- googleadsagent.ai — Production system (Buddy)