mcp-google-ads
Multi-account Google Ads MCP server for operators who need one MCP surface across multiple client
or in-house ad accounts without restarting the server.
Release posture: beta package, version 0.1.0 from pyproject.toml.
Choose your path
Architecture
flowchart TD
U[AI operator] --> C[MCP client]
C --> S[FastMCP server]
S --> M[Account manager]
M --> F[Accounts config]
S --> Q[GAQL query helpers]
Q --> R[Retry wrapper]
R --> A[Google Ads API]
A --> R --> S
Request flow
flowchart TD
P[Operator asks for account or campaign data] --> T[Selected MCP tool]
T --> A[Resolve named or default account]
A --> B[Build Google Ads client]
B --> C[Run GAQL query]
C --> D{API call succeeds?}
D -- yes --> E[Normalize rows and return]
D -- retryable --> F[Backoff and retry]
F --> D
D -- no --> G[Return error payload]
Quick start
- Install the package.
python -m pip install mcp-google-ads-multi
- Copy the accounts config template and add your accounts.
mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json
- Register it in your MCP client.
{
"mcpServers": {
"google-ads": {
"command": "uvx",
"args": ["mcp-google-ads-multi"],
"env": {
"GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
"GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
}
}
}
}
Available tools
| Tool group | Tools | Purpose |
|---|
| Account selection | list_accounts, set_default_account, list_customers | Manage account routing and discover accessible customers |
| Spend summary | get_account_summary, compare_periods | Period-over-period account reporting |
| Campaign analysis | list_campaigns, get_campaign_performance | Campaign inventory and range-based metrics |
| Query-level detail | get_keyword_performance, search_terms_report, get_ad_performance | Keyword, search-term, and ad reporting |
Runtime proof
Repo map
Validation
| Check | Command |
|---|
| Import compiles | python -m compileall gads |
| Package builds | python -m build |
| README/docs links are local | rg '\\]\\(([^)]+\\.md)\\)' README.md docs/ |
License
MIT
Project context for new tasks
Read prompt.md, then INDEX.md, for project-specific decisions, task routes and current handoff. Historical examples do not select the current task.