mcp-google-ads
Use this MCP server to query and compare Google Ads performance across multiple configured accounts through one tool surface.
List configured accounts, set the default account, and discover accessible customer accounts or MCC children.
Get top-level account spend/conversion totals and compare performance between two date ranges.
List campaigns and retrieve campaign performance metrics for a date range, optionally filtered by campaign.
Pull keyword-level performance including quality scores, search terms reports, and ad-level performance with headlines, descriptions, CTR, and conversions.
Route queries by named/default account and customer ID, with GAQL query helpers and retry/backoff for API calls.
Allows querying and analyzing Google Ads accounts, including campaign performance, keywords, search terms, and account analytics, with support for multiple accounts and OAuth/service account authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-google-ads Show me campaign performance for account my-client last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | Quick start below | |
Auditing account switching and retries | ||
Reviewing packaging metadata |
Related MCP server: Google Ads MCP Server
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 --> SRequest 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-multiCopy the accounts config template and add your accounts.
mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.jsonRegister 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 |
| Manage account routing and discover accessible customers |
Spend summary |
| Period-over-period account reporting |
Campaign analysis |
| Campaign inventory and range-based metrics |
Query-level detail |
| Keyword, search-term, and ad reporting |
Runtime proof
Claim | Proof |
Package entry point is stable |
|
Multi-account routing is first-class |
|
Queries go through reusable helpers | |
Config is file-driven |
|
Repo map
Path | Purpose |
FastMCP tool surface | |
Account config, OAuth/service-account loading | |
GAQL execution helpers | |
Retry behavior for API calls | |
Setup, validation, common failures | |
Component map and request lifecycle |
Validation
Check | Command |
Import compiles |
|
Package builds |
|
README/docs links are local |
|
License
MIT
Project context for new tasks
Use INDEX.md to find task-specific contracts; consult prompt.md when product direction is relevant. Historical examples do not select the current task.
Available Tools
10 toolscompare_periodsC
Compare performance between two date ranges.
Inputs: customer_id (required), period1_end (required), period2_end (required), period1_start (required), +3 more. Returns: object
get_account_summaryB
Get top-level spend and conversion totals for an account.
Inputs: end_date (required), start_date (required), customer_id (required), account. Returns: object
get_ad_performanceB
Get ad-level performance (headlines, descriptions, CTR, conversions).
Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result
get_campaign_performanceC
Get campaign performance metrics for a date range.
Inputs: end_date (required), start_date (required), customer_id (required), account, +1 more. Returns: result
get_keyword_performanceA
Get keyword-level performance including quality scores.
Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result
list_accountsB
List all configured Google Ads accounts and which is the current default.
Inputs: no named parameters. Returns: result
list_campaignsC
List campaigns for an account.
Inputs: customer_id (required), status, account. Returns: result
list_customersA
List all accessible Google Ads customer accounts.
If customer_id is provided, lists child accounts under that MCC. Otherwise lists all accessible accounts for this login.
Inputs: account, customer_id. Returns: result
search_terms_reportB
Get actual search terms that triggered your ads.
Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result
set_default_accountA
Set the default account used when no account is specified in other tools.
Inputs: account (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools are clearly distinct by entity (accounts, campaigns, keywords, ads) and action (list, get, set, compare). However, list_accounts and list_customers both list accounts with subtle differences (configured vs accessible) that could cause confusion.
Tool names predominantly follow a verb_noun pattern (list_*, get_*, set_*). The deviations are 'compare_periods' (verb_noun but not get/list) and 'search_terms_report' (noun phrase without a verb), but the overall pattern is still readable and predictable.
Ten tools is well within the ideal range for a domain-specific server. Each tool covers a distinct aspect of Google Ads reporting and account management, and none feel redundant or excessive.
The server provides comprehensive read/reporting coverage: account listing, summaries, campaign/keyword/ad performance, search terms, and period comparison. It lacks management operations like creating or updating campaigns, but this seems intentionally scoped to analytics and account selection, so the gaps are minor.
Related MCP Connectors
Google Ads MCP server — manage campaigns, keywords, and metrics.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted Google Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
AlicenseBqualityAmaintenanceMCP server that provides tools and resources for interacting with Google Ads API, enabling search, metadata retrieval, and account management through natural language.76,732 PyPI1,193Apache 2.0- AlicenseNot gradedqualityDmaintenanceA comprehensive Google Ads MCP server providing ~47 tools for full read/write access to Google Ads accounts, including campaign management, ad creation, keyword management, and reporting.2Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables authorized users to securely connect to and manage their Google Ads accounts through MCP clients, with support for campaigns, ad groups, ads, keywords, reporting, and billing. Runs as a remote multi-user server on Cloudflare Workers with per-user authentication and safety controls.-
- AlicenseNot gradedqualityDmaintenanceMCP server for managing Google Ads campaigns through the official Google Ads API, covering accounts, campaigns, budgets, keywords, search terms, and keyword ideas. It provides tools for both reading and mutating live ads data, such as pausing campaigns, updating budgets, and adding keywords.MIT