MCP Google Ads

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

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

1. Install the package.

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

2. 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

3. 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

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

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.