Skip to main content
Glama
Google Ads MCP

Google Ads MCP

Google Ads MCP

Manage Google Ads campaigns through an AI assistant — safely, with every write gated behind a preview and an audit log.

CI Python 3.10+ License: MIT

A Model Context Protocol server that exposes Google Ads API v24 operations as tools for Claude (or any MCP client). Read campaign metrics, search terms, and recommendations; make controlled changes to bids, budgets, statuses, and creative — all from a single conversation.


Features

31 tools across five capability layers:

Read-only reporting

Tool

What it does

list_accessible_customers

List all accounts under the MCC

get_campaigns

List campaigns with status and channel type

get_campaign_performance

Clicks, impressions, cost, conversions, CTR

get_ad_groups

List ad groups with status

get_keywords

Keywords with match type and status

get_search_terms

Actual search queries with performance metrics

get_change_events

Account change history

run_gaql_query

Execute any read-only GAQL query (up to 10k rows)

get_segments_metadata

Available GAQL segments

get_metrics_metadata

Available GAQL metrics

get_resource_metadata

Fields for any GAQL resource

Recommendations & planning

Tool

What it does

get_recommendations

Active Google Ads recommendations for an account or campaign

generate_keyword_ideas

Keyword ideas from seed keywords or a URL

get_forecast_metrics

Bid simulations and forecast data

apply_recommendation

Apply a recommendation (gated)

dismiss_recommendation

Dismiss a recommendation (gated)

Status writes (gated)

Tool

What it does

pause_campaign / enable_campaign

Toggle campaign status

pause_ad_group / enable_ad_group

Toggle ad group status

pause_keyword / enable_keyword

Toggle keyword status

pause_ad / enable_ad

Toggle ad status

Bid & budget writes (gated + capped)

Tool

What it does

update_keyword_bid

Set keyword max CPC — capped at ±25% by default

update_ad_group_bid

Set ad group default CPC — capped

update_campaign_budget

Set daily budget — capped at ±20% by default

Entity creation (gated)

Tool

What it does

create_campaign

Create campaign + shared budget atomically (starts paused)

create_ad_group

Create ad group under a campaign

create_keyword

Add keyword to an ad group

create_ad

Create a responsive search ad (starts paused)


Related MCP server: Google Ads MCP

Safety model

Every write passes through four sequential gates:

1. Allowlist  — customer_id must be in GOOGLE_ADS_MUTATE_ALLOWLIST (default: deny all)
2. Cap        — bid/budget changes exceeding the configured % are blocked outright
3. Preview    — confirm=False (default) runs validate_only; nothing changes in the account
4. Audit      — confirmed mutations are appended to an append-only JSONL log (chmod 0600)

New entities (campaigns, ad groups, keywords, ads) always start paused.

Transient quota errors (RESOURCE_TEMPORARILY_EXHAUSTED) are retried automatically with exponential back-off and jitter (configurable via GOOGLE_ADS_MAX_RETRIES, default 3).


Setup

Prerequisites

  • Python 3.10+

  • uv

  • A Google Ads developer token and manager account (MCC)

Install

git clone https://github.com/LucasSantana-Dev/google-ads-mcp
cd google-ads-mcp
uv sync --extra dev

Credentials

cp .env.example .env

Variable

Description

GOOGLE_ADS_CLIENT_ID

OAuth 2.0 Desktop App client ID

GOOGLE_ADS_CLIENT_SECRET

OAuth 2.0 Desktop App client secret

GOOGLE_ADS_DEVELOPER_TOKEN

Your Google Ads developer token

GOOGLE_ADS_LOGIN_CUSTOMER_ID

MCC account ID (digits only, no hyphens)

GOOGLE_ADS_REFRESH_TOKEN

Long-lived OAuth refresh token (see below)

GOOGLE_ADS_MUTATE_ALLOWLIST

Comma-separated customer IDs that may receive writes

GOOGLE_ADS_AUDIT_LOG

Audit log path (default: audit-log.jsonl)

GOOGLE_ADS_MAX_BID_CHANGE_PCT

Max bid change fraction (default: 0.25)

GOOGLE_ADS_MAX_BUDGET_CHANGE_PCT

Max budget change fraction (default: 0.20)

GOOGLE_ADS_MAX_RETRIES

Quota retry attempts (default: 3)

Mint a refresh token

GOOGLE_ADS_CLIENT_ID=... GOOGLE_ADS_CLIENT_SECRET=... \
  uv run python scripts/get_refresh_token.py

A browser opens for OAuth consent. Copy the printed refresh token into .env.


Claude Desktop integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/<you>/.local/bin/uv",
      "args": [
        "run",
        "--directory", "/path/to/google-ads-mcp",
        "--env-file", "/path/to/google-ads-mcp/.env",
        "python", "-m", "google_ads_mcp.server"
      ]
    }
  }
}

Restart Claude Desktop. The 31 tools appear automatically.


Example conversations

# Reporting
"Show me all campaigns for account 123-456-7890 with spend > $100 this week"
"What search terms triggered our branded keywords in the last 7 days?"
"Any keyword ideas for 'project management software'?"
"What recommendations does Google have for my account?"

# Writes — always previews first; apply with confirm=true
"Pause campaign 9876543, it's burning budget"
"Set the CPC bid for keyword 111 in ad group 222 to $1.50"
"Create a new Search campaign 'Brand Q3' with a $20/day budget"
"Apply the 'add keyword' recommendation for campaign 555"

Development

uv run pytest                          # 102 tests, 89% coverage
uv run ruff check src/ tests/          # lint
uv run mypy src/                       # type check

CI runs on every push and pull request.


Architecture

src/google_ads_mcp/
├── server.py          # FastMCP entrypoint, tool registration
├── config.py          # GoogleAdsClient factory (reads .env)
├── gaql.py            # GAQL execution, validators, row serialization, retry
├── mutate.py          # Write-safety harness (allowlist → cap → preview → audit)
├── retry.py           # Exponential back-off for quota errors
├── errors.py          # tool_handler wrapper → {success, error} for any exception
├── testing.py         # FakeGoogleAdsClient — unit tests without network or credentials
└── tools/
    ├── accounts.py        # list_accessible_customers
    ├── campaigns.py       # get_campaigns, get_campaign_performance
    ├── adgroups.py        # get_ad_groups
    ├── keywords.py        # get_keywords, get_search_terms
    ├── changes.py         # get_change_events
    ├── query.py           # run_gaql_query
    ├── metadata.py        # get_*_metadata (3 tools)
    ├── writes_status.py   # pause/enable campaign/ad_group/keyword/ad (8 tools)
    ├── writes_value.py    # update keyword bid, ad group bid, campaign budget (3 tools)
    ├── creates.py         # create campaign, ad group, keyword, ad (4 tools)
    └── planning.py        # recommendations, keyword ideas, forecast (5 tools)

Transport: stdio only — no HTTP port, no public exposure.
Auth: OAuth 2.0 Desktop App + refresh token. Credentials stay on the local machine.


License

MIT

Available Tools

31 tools
apply_recommendationA

Apply a recommendation (e.g. add a keyword, raise a bid).

Inputs: customer_id (required), recommendation_resource_name (required), confirm. Returns: object

create_adA

Create a new responsive search ad (paused by default).

Inputs: headlines (required), final_urls (required), ad_group_id (required), customer_id (required), +2 more. Returns: object

create_ad_groupA

Create a new ad group (paused by default).

Inputs: name (required), campaign_id (required), customer_id (required), confirm, +1 more. Returns: object

create_campaignA

Create a new campaign (paused by default).

Inputs: name (required), customer_id (required), budget_amount_micros (required), confirm, +1 more. Returns: object

create_keywordC

Create a new keyword (enabled by default).

Inputs: ad_group_id (required), customer_id (required), keyword_text (required), confirm, +2 more. Returns: object

dismiss_recommendationA

Dismiss a recommendation (mark as not applicable).

Note: The Google Ads API does not support validate_only for dismiss, so preview returns the intent without calling the API.

Inputs: customer_id (required), recommendation_resource_name (required), confirm. Returns: object

enable_adB

Enable an ad (ad group ad). Previews unless confirm=true.

Inputs: ad_id (required), ad_group_id (required), customer_id (required), confirm. Returns: object

enable_ad_groupC

Enable an ad group. Previews unless confirm=true.

Inputs: ad_group_id (required), customer_id (required), confirm. Returns: object

enable_campaignA

Enable (resume) a campaign. Previews unless confirm=true.

Inputs: campaign_id (required), customer_id (required), confirm. Returns: object

enable_keywordA

Enable a keyword (ad group criterion). Previews unless confirm=true.

Inputs: ad_group_id (required), customer_id (required), criterion_id (required), confirm. Returns: object

generate_keyword_ideasB

Generate keyword ideas using Google's Keyword Planner.

Inputs: customer_id (required), url, limit, keywords, +2 more. Returns: object

get_ad_groupsB

Get ad groups for a customer, with optional filtering by campaign and status.

Inputs: customer_id (required), limit, campaign_id, status_filter. Returns: object

get_campaign_performanceA

Get campaign performance metrics for a date range, ordered by cost descending.

Inputs: date_end (required), date_start (required), customer_id (required), limit. Returns: object

get_campaignsB

Get campaigns for a customer, optionally filtered by status.

Inputs: customer_id (required), limit, status_filter. Returns: object

get_change_eventsA

Retrieve change events for a customer account within a date range.

The change_event resource requires a date filter, an ORDER BY clause, and a LIMIT (hard-capped at 10,000 rows by the API). The Google Ads API typically supports a ~30-day lookback window for change events; queries beyond that range may return empty results.

Inputs: date_end (required), date_start (required), customer_id (required), limit. Returns: object

get_forecast_metricsC

Fetch forecast metrics and bid simulations for a campaign.

Inputs: campaign_id (required), customer_id (required), limit. Returns: object

get_keywordsC

Retrieve keywords from an ad group, optionally filtered by match type.

Inputs: customer_id (required), limit, ad_group_id, match_type_filter. Returns: object

get_metrics_metadataA

List all available GAQL metrics with metadata.

Returns a list of metric field objects with name, category, data_type, selectable, filterable, and sortable attributes.

Inputs: no named parameters. Returns: object

get_recommendationsA

Fetch active recommendations for an account or campaign.

Inputs: customer_id (required), limit, campaign_id. Returns: object

get_resource_metadataA

Get all available fields for a specific resource.

Inputs: resource_name (required). Returns: object

get_search_termsA

Retrieve search terms that matched keywords, filtered by date and optional criteria.

Search terms are ordered by clicks (descending) to prioritize high-engagement terms.

Inputs: date_end (required), date_start (required), customer_id (required), limit, +2 more. Returns: object

get_segments_metadataA

List all available GAQL segments with metadata.

Returns a list of segment field objects with name, category, data_type, selectable, filterable, and sortable attributes.

Inputs: no named parameters. Returns: object

list_accessible_customersA

List the Google Ads customer accounts the credentials can access.

Returns digit-only customer ids to use as customer_id for other tools.

Inputs: no named parameters. Returns: object

pause_adA

Pause an ad (ad group ad). Previews unless confirm=true.

Inputs: ad_id (required), ad_group_id (required), customer_id (required), confirm. Returns: object

pause_ad_groupC

Pause an ad group. Previews unless confirm=true.

Inputs: ad_group_id (required), customer_id (required), confirm. Returns: object

pause_campaignA

Pause a campaign. Previews unless confirm=true; customer must be allowlisted.

Inputs: campaign_id (required), customer_id (required), confirm. Returns: object

pause_keywordB

Pause a keyword (ad group criterion). Previews unless confirm=true.

Inputs: ad_group_id (required), customer_id (required), criterion_id (required), confirm. Returns: object

run_gaql_queryA

Run a read-only GAQL query against a customer account.

This is the explicit raw-query escape hatch: the query is passed through as-is, so the caller is responsible for valid GAQL. Use get_segments_metadata / get_metrics_metadata / get_resource_metadata first to discover valid field names. customer_id is validated.

Inputs: query (required), customer_id (required), limit. Returns: object

update_ad_group_bidA

Set an ad group's default max CPC bid (micros). Previews unless confirm=true; capped.

Inputs: ad_group_id (required), customer_id (required), cpc_bid_micros (required), confirm. Returns: object

update_campaign_budgetA

Set a campaign's daily budget (micros). Previews unless confirm=true; change is capped.

Resolves the campaign's shared budget resource first, then mutates it.

Inputs: campaign_id (required), customer_id (required), amount_micros (required), confirm. Returns: object

update_keyword_bidA

Set a keyword's max CPC bid (micros). Previews unless confirm=true; change is capped.

Inputs: ad_group_id (required), customer_id (required), criterion_id (required), cpc_bid_micros (required), +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 31 tools

    Disambiguation5/5

    Every tool targets a distinct resource or action (e.g., create_ad vs. create_campaign, get_keywords vs. get_recommendations). No two tools have overlapping purposes, and even similar verbs like 'enable' and 'pause' are clearly separated by entity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_campaign, get_keywords, pause_ad). Verbs like 'apply', 'dismiss', 'generate', 'list', 'run' are distinct and appropriately used. No mixing of casing or other conventions.

    Tool Count5/5

    With 31 tools, the server covers a broad range of Google Ads operations without becoming unwieldy. Each tool serves a specific purpose, and the count is reasonable given the complexity of the domain.

    Completeness2/5

    The toolset lacks update operations for most entities (e.g., no update_ad, update_campaign, update_ad_group) and no removal tools. While raw GAQL queries can fill some gaps, the surface is incomplete for standard lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables managing and analyzing ad accounts in plain language from AI assistants, including cross-account performance reports, keyword research, GAQL queries, and safe previewed changes.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to make guarded, two-step changes to Google Ads accounts, including pausing and resuming campaigns, ad groups, and keywords, adjusting budgets, adding negative keywords, creating search campaigns and ads, and switching bidding settings.
      13
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read and modify a Google Ads account by running reports and creating or editing campaigns, budgets, ad groups, keywords, ads, and conversion actions, with validation-only and paused-by-default safeguards.
      MIT