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

You are...	Start here	Then
Connecting the server to your MCP client	docs/start-here.md	Quick start below
Auditing account switching and retries	docs/architecture.md	`gads/server.py`
Reviewing packaging metadata	`pyproject.toml`	`accounts.example.json`

Architecture

mermaid

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

mermaid

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.

bash

python -m pip install mcp-google-ads-multi

Copy the accounts config template and add your accounts.

bash

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json

config.json

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

Claim	Proof
Package entry point is stable	`mcp-google-ads-multi = "gads.server:main"` in `pyproject.toml`
Multi-account routing is first-class	`AccountManager()` and `set_default_account()` in `gads/server.py`
Queries go through reusable helpers	`gads/query.py` and `gads/retry.py`
Config is file-driven	`accounts.example.json` documents the accounts shape

Repo map

Path	Purpose
`gads/server.py`	FastMCP tool surface
`gads/accounts.py`	Account config, OAuth/service-account loading
`gads/query.py`	GAQL execution helpers
`gads/retry.py`	Retry behavior for API calls
`docs/start-here.md`	Setup, validation, common failures
`docs/architecture.md`	Component map and request lifecycle

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