Google Ads MCP
Allows management of Google Ads campaigns through an AI assistant, including reading campaign metrics, search terms, recommendations, and making controlled changes to bids, budgets, statuses, and creative, with safety gates like allowlist, caps, preview, and audit log.
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., "@Google Ads MCP get campaign performance for this 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.
Google Ads MCP
Manage Google Ads campaigns through an AI assistant — safely, with every write gated behind a preview and an audit log.
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 all accounts under the MCC |
| List campaigns with status and channel type |
| Clicks, impressions, cost, conversions, CTR |
| List ad groups with status |
| Keywords with match type and status |
| Actual search queries with performance metrics |
| Account change history |
| Execute any read-only GAQL query (up to 10k rows) |
| Available GAQL segments |
| Available GAQL metrics |
| Fields for any GAQL resource |
Recommendations & planning
Tool | What it does |
| Active Google Ads recommendations for an account or campaign |
| Keyword ideas from seed keywords or a URL |
| Bid simulations and forecast data |
| Apply a recommendation (gated) |
| Dismiss a recommendation (gated) |
Status writes (gated)
Tool | What it does |
| Toggle campaign status |
| Toggle ad group status |
| Toggle keyword status |
| Toggle ad status |
Bid & budget writes (gated + capped)
Tool | What it does |
| Set keyword max CPC — capped at ±25% by default |
| Set ad group default CPC — capped |
| Set daily budget — capped at ±20% by default |
Entity creation (gated)
Tool | What it does |
| Create campaign + shared budget atomically (starts paused) |
| Create ad group under a campaign |
| Add keyword to an ad group |
| 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+
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 devCredentials
cp .env.example .envVariable | Description |
| OAuth 2.0 Desktop App client ID |
| OAuth 2.0 Desktop App client secret |
| Your Google Ads developer token |
| MCC account ID (digits only, no hyphens) |
| Long-lived OAuth refresh token (see below) |
| Comma-separated customer IDs that may receive writes |
| Audit log path (default: |
| Max bid change fraction (default: |
| Max budget change fraction (default: |
| Quota retry attempts (default: |
Mint a refresh token
GOOGLE_ADS_CLIENT_ID=... GOOGLE_ADS_CLIENT_SECRET=... \
uv run python scripts/get_refresh_token.pyA 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 checkCI 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 toolsapply_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
Scored across 31 tools
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.
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.
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.
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
Related MCP Connectors
- AdCopilotDeprecatedcloud.adcopilot
Google Ads, GA4, Search Console and Tag Manager for AI assistants. Every change is proposed first.
Manage Google, Meta, TikTok, Snapchat and LinkedIn ads, plus GA4, Tag Manager and Search Console, by chat from Claude or ChatGPT. Spend increases need your confirmation first.
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables reading and analyzing Google Ads data, planning keywords, and previewing campaign changes before applying them, all through natural language.351Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseBqualityCmaintenanceEnables 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.13MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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