ads-mcp
ads-mcp is a Google Ads MCP server that lets AI agents read Google Ads account data and reports, and optionally stage/apply account changes through a guarded review flow.
Run authenticated health checks and get account identity, currency, time zone, and manager/test flags.
Execute raw GAQL queries on any accessible resource with bounded, paginated results.
Pull performance reports for campaigns, ads, keywords, search terms, geo, and Shopping products using explicit date ranges or last_n_days.
List accounts under a manager login and inspect conversion actions, negative keywords, extensions, policy issues, recommendations, change history, listing groups, and Merchant Center product status.
Discover keyword ideas and get keyword forecasts without creating anything in the account.
Search geo target constants by name.
Optionally enable experimental writes: create change plans, dry-run previews, apply with audit logging and budget/CPC caps, and require extra acknowledgement for irreversible changes.
Read-only by default; writes are opt-in and guarded.
Integrates with Google Ads to provide tools for reading campaign, ad group, ad, and keyword data, plus a management surface for staging and applying changes such as pause, enable, and remove operations with budget and bid limits.
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., "@ads-mcp what was the spend and clicks for each campaign this week?"
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.
ads-mcp
A Google Ads MCP server for agents. Query accounts and reports, or stage changes for review before applying them. Read-only by default.
The source is publicly available under Apache License 2.0. Install from source; the package is not published to PyPI. Write support is experimental. Supports CPython 3.12–3.14 on Linux and macOS; native Windows is unsupported. Requires Google Ads SDK 31.4.0 or later within major 31.
34 read tools: authenticated health checks, account and PMax inspection, performance reports, Keyword Planner and raw GAQL with bounded responses.
Reviewed changes: write tools create plans; application checks account binding, expiry, preview requirements and configured budget/CPC limits.
Traceable execution: write mode requires an audit log. Uncertain writes are surfaced and never retried automatically; transient reads use bounded retries.
Install
Install from source into a virtual environment:
git clone https://github.com/Overcast-Solutions/ads-mcp.git
cd ads-mcp
python3.12 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/ads-mcp --versionFor commit-pinned installation and read-only-first validation, follow the installation and validation guide.
Related MCP server: meta-ads-mcp
OAuth setup (one-time)
Bring your own credentials. Each installer must use a Google Cloud project and OAuth client they control, plus a Google account authorized for their Ads accounts. The package provides no shared project, maintainer credentials or hosted authentication service.
Enable the Google Ads API in your project and create a Desktop app OAuth client. Download its JSON to private, encrypted storage.
Review authentication and API access for project approval, consent-screen settings, access levels and token lifetimes.
Generate your refresh token using the downloaded client JSON:
export GOOGLE_ADS_CREDENTIALS_PATH="/absolute/private/path/oauth_client.json"
export GOOGLE_ADS_TOKEN_PATH="/absolute/private/path/token.json"
.venv/bin/ads-mcp-generate-tokenComplete Google's consent flow yourself. Keep credentials, tokens, account data and audit records on operator-managed encrypted storage. Never send credential files or tokens to maintainers or paste them into issues or model prompts. Internal teams may use their own authorized installation; independent users must configure their own credentials. Review the operator guide before connecting account data to an MCP host or model provider.
Claude Code / MCP registration
For clients using mcpServers configuration, replace the executable path,
credential paths and account IDs below with your own. Omit
GOOGLE_ADS_LOGIN_CUSTOMER_ID if you are not using a manager login.
{
"mcpServers": {
"ads-mcp-readonly": {
"type": "stdio",
"command": "/absolute/path/to/ads-mcp/.venv/bin/ads-mcp",
"env": {
"GOOGLE_ADS_CUSTOMER_ID": "123-456-7890",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "111-222-3333",
"GOOGLE_ADS_CREDENTIALS_PATH": "/absolute/private/path/oauth_client.json",
"GOOGLE_ADS_TOKEN_PATH": "/absolute/private/path/token.json",
"ADS_MCP_READ_ONLY": "true"
}
}
}
}Call health_check to verify authenticated access, then get_account_info
to confirm the account. Metric reports require an explicit date window or
last_n_days; see the reporting guide.
For a read-only rollout alongside an existing server, follow the integration and migration guide.
Experimental writes
Enabling writes exposes 84 operations. Read the write guide
before opting in. Writes require audit
storage and the appropriate caps; the default flow is plan → dry-run preview →
confirm_and_apply. Irreversible changes require an additional acknowledgement.
Budget and CPC caps apply per operation. They do not cap aggregate account spend or CPA/ROAS targets. Enabling existing entities can also affect spend. Use independent account controls and review the guide's full limit scope.
Documentation
Guide | What it covers |
Your OAuth client, token storage and Google API access | |
Environment variables, defaults and audit storage | |
GAQL, pagination, date windows, history and forecasts | |
Plans, spend limits, creation requirements and validation | |
Search defaults, precise updates and network reporting | |
Inspect and update existing ad and keyword destinations | |
Shared negative lists and explicit ad-group demographics | |
Asset groups, signals, URL controls and Item-ID selection | |
Same-campaign URL tests, results and promotion observation | |
Refusals, recovery and uncertain outcomes | |
Every tool's parameters and defaults | |
Account authority, data handling and host responsibilities | |
Consumer compatibility and read-only rollout |
For development and redistribution, see contributing, release checks and security.
License
Apache License 2.0. Dependencies retain their own licenses; review applicable obligations when redistributing them or adding bundled material.
Available Tools
21 toolsdiscover_keywordsA
Keyword ideas for seed terms and/or a page URL, with average monthly searches and competition. Computed by KeywordPlanIdeaService — nothing is created in the account. Bounded by the row limit with pagination tokens.
Inputs: page_url, page_token, customer_id, seed_keywords.
get_account_infoC
Account identity: id, name, currency, time zone, auto-tagging, manager/test flags — from a live authenticated read.
Inputs: customer_id.
get_ad_performanceC
Ad-level metrics for a date window; bounded with pagination tokens.
Inputs: page_token, campaign_id, customer_id, last_n_days, +2 more.
get_campaign_performanceB
Campaign metrics for a date window (explicit range or last_n_days), with budget, bidding strategy incl. targets, and the serving/primary status trio. Money is decimal with currency. enabled_only=true filters server-side.
Inputs: page_token, campaign_id, customer_id, last_n_days, +3 more.
get_change_historyA
Who changed what, when, with which client: change events with actor email, client type, and old/new values per changed field. Strict YYYY-MM-DD dates, inclusive from 29 days before today through today in the verified account time zone. Includes the complete end date, including fractional seconds, up to but excluding the next calendar day's midnight. This local 30-calendar-date policy is distinct from provider sub-day retention. LIMIT 1000; a full result signals possibly_truncated on every local page with narrowing guidance. Local tokens cannot recover beyond that cap. More than 1000 events at one timestamp may need a different run_gaql query; upstream maximum LIMIT 10000.
Inputs: date_range_end (required), date_range_start (required), page_token, customer_id, +1 more.
get_conversion_actionsC
Conversion actions with category, type, status, counting type, and primary-for-goal flags.
Inputs: customer_id.
get_geo_performanceB
Geographic performance for a date window; bounded with pagination tokens.
Inputs: page_token, campaign_id, customer_id, last_n_days, +2 more.
get_keyword_forecastsA
Forecast clicks, cost, and average CPC for supplied keywords. Impressions are unavailable from the v25 nonpersisting API and returned as null. Other absent estimates are null; explicit zero and fractional clicks are preserved. Uses a strict YYYY-MM-DD date range. Start must be in the future and end within one calendar year of today in the requested account's time zone (February 29 clamps to February 28). Defaults to the next 30 complete account-local days; missing or invalid account time zones are refused. Money is decimal with the account currency. Computed by KeywordPlanIdeaService — no KeywordPlan is ever created. keyword_texts is an alias for keywords; both must agree if supplied.
Inputs: keywords, customer_id, keyword_texts, date_range_end, +1 more.
get_keyword_performanceB
Keyword metrics (text, match type, bid, quality signals) for a date window; bounded with pagination tokens.
Inputs: page_token, campaign_id, customer_id, last_n_days, +2 more.
get_listing_groupsB
Listing-group trees per PMax asset group and standard Shopping ad group for the requested campaign, preserving parent links, dimensions, and exclusions. Empty trees are valid results.
Inputs: campaign_id (required), customer_id.
get_negative_keywordsC
Campaign-level negative keywords.
Inputs: customer_id.
get_policy_issuesA
Policy issues across ads, PMax asset-group assets, and campaign-linked sitelink assets. mode=summary returns a bounded topic histogram + entity-status breakdown; mode=full paginates with filters (enabled_only, campaign_id, topic) — never an unbounded dump.
Inputs: mode, topic, page_token, campaign_id, +2 more.
get_product_statusA
Merchant Center feed health as visible from the Ads API: linked merchant id, product counts by eligibility status scoped to the requested campaign and linked merchant. A campaign without a feed link returns NOT_FEED_LINKED, not an error.
Inputs: campaign_id (required), customer_id.
get_search_termsB
Search-term report for a date window; bounded with pagination tokens — no unbounded dumps.
Inputs: page_token, campaign_id, customer_id, last_n_days, +2 more.
get_shopping_performanceC
Product-level shopping metrics for a campaign and date window.
Inputs: campaign_id (required), page_token, customer_id, last_n_days, +2 more.
health_checkA
Truthful liveness: performs a real authenticated Google Ads read and reports config, credentials, and guardrail state. OK means the API answered — never that config files merely exist.
Inputs: no named parameters.
list_accountsC
Accessible accounts under the configured login customer.
Inputs: no named parameters.
list_extensionsC
Campaign-level extensions/assets (sitelinks, callouts, structured snippets) with status.
Inputs: customer_id.
list_recommendationsA
Google's active recommendations with typed impact projections (base vs potential cost and conversions). Read-only; applying or dismissing routes through the guardrail plan flow.
Inputs: customer_id.
run_gaqlA
Execute a raw GAQL query and return rows in json, table, or csv format. The workhorse read: any resource, any field the API exposes, passed through faithfully.
Inputs: query (required), format, page_size, page_token, +1 more.
search_geo_targetsB
Search geo target constants by name (e.g. 'United States').
Inputs: query (required), customer_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
The specialized getters map cleanly to distinct resources, and run_gaql is explicitly framed as a raw GAQL escape hatch rather than a parallel typed reader. A couple of boundaries require care—run_gaql can technically produce any read result, and list_accounts vs get_account_info both concern account context—but descriptions keep the ambiguity minor.
The set overwhelmingly follows snake_case verb_noun naming, with get_* dominating and list_* used for a few collection reads. Minor deviations like run_gaql, health_check, search_geo_targets, and discover_keywords are readable but break the otherwise regular get_/list_ pattern.
At 21 tools, the surface is on the heavy side, and many get_*_performance helpers are structurally similar and could feel redundant next to run_gaql. The breadth is defensible for Google Ads reporting, but the set sits in the 16–25 range that feels borderline rather than tight.
For what appears to be a read-only/reporting server, coverage is broad: accounts, campaigns, ads, keywords, search terms, geo, conversion actions, policies, recommendations, change history, shopping, and product status are all represented. Minor gaps such as a dedicated ad-group performance or audience report exist, but run_gaql is a genuine escape hatch for arbitrary reads.
Maintenance
Related MCP Connectors
Google Ads MCP with 20,000+ account peer context and staged approve-then-execute writes.
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Manage Google, Microsoft, ChatGPT and Meta Ads safely: previewed, logged, revertible changes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading and writing the Google Ads API for full campaign management, with a dry-run/confirm safety flow on every write.MIT
- FlicenseNot gradedqualityCmaintenanceEnables read-only Meta Ads reporting and diagnostics, plus safe, preview-before-apply mutations such as campaign creation, duplication, targeting replacement, and attribution changes.-
- AlicenseAqualityCmaintenanceEnables MCP clients to read campaign and account data freely while routing every write through human-approved plans, with budget caps, drift refusal, undo, and audit logging.6MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to retrieve Google Ads performance data, run GAQL queries and keyword planner research, and create or manage search and P-MAX campaigns, budgets, keywords, and ad status. Includes safety defaults such as paused creation and read-only mode.16MIT