Skip to main content
Glama
ads-mcp

ads-mcp

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 --version

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

  1. Enable the Google Ads API in your project and create a Desktop app OAuth client. Download its JSON to private, encrypted storage.

  2. Review authentication and API access for project approval, consent-screen settings, access levels and token lifetimes.

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

Complete 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

Authentication

Your OAuth client, token storage and Google API access

Configuration

Environment variables, defaults and audit storage

Reporting

GAQL, pagination, date windows, history and forecasts

Writes

Plans, spend limits, creation requirements and validation

Campaign networks

Search defaults, precise updates and network reporting

Search URLs

Inspect and update existing ad and keyword destinations

Shared targeting

Shared negative lists and explicit ad-group demographics

Performance Max

Asset groups, signals, URL controls and Item-ID selection

PMax experiments

Same-campaign URL tests, results and promotion observation

Errors

Refusals, recovery and uncertain outcomes

Tool catalog

Every tool's parameters and defaults

Operator guide

Account authority, data handling and host responsibilities

Integration and migration

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 tools
discover_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

    B3.2/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading and writing the Google Ads API for full campaign management, with a dry-run/confirm safety flow on every write.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only Meta Ads reporting and diagnostics, plus safe, preview-before-apply mutations such as campaign creation, duplication, targeting replacement, and attribution changes.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      16
      MIT