itallstartedwithaidea 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.git
2. 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-7890
Or point to an existing google-ads.yaml:
GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890
3. Run
python -m ads_mcp.server
Claude 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)