google-ads-mcp
Provides tools for managing Google Ads campaigns, including reading performance data, auditing, and executing write operations like budget updates, campaign creation, and keyword management.
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 show me campaign performance for last 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.
googleadsagent-mcp
An MCP (Model Context Protocol) server + standalone agent SDK for the Google Ads API.
Built by googleadsagent.ai · MIT License
English | Français | Español | 中文 | Nederlands | Русский | 한국어
Install
# From PyPI (once published)
pip install googleadsagent-mcp
# From GitHub right now
pip install git+https://github.com/itallstartedwithaidea/google-ads-mcp.git
# With uv
uv add googleadsagent-mcp
# From source
git clone https://github.com/itallstartedwithaidea/google-ads-mcp.git && cd google-ads-mcp && pip install -e .Related MCP server: google-ads-mcp
Works with every MCP client
Client | Transport | Config |
Claude Code | stdio |
|
Claude Desktop | stdio |
|
Cursor / Windsurf | stdio | Settings → MCP → |
OpenAI Agents SDK | stdio |
|
LangChain | stdio |
|
Remote / Cloud | HTTP SSE |
|
Quick Start
# 1. Copy and fill credentials
cp .env.example .env
# 2. Validate environment
python scripts/validate.py
# 3a. Run as MCP server (stdio — Claude Desktop/Cursor/Claude Code)
python -m ads_mcp.server
# 3b. Run as MCP server (HTTP — remote agents)
python -m ads_mcp.server --http
# 3c. Run as standalone agent CLI
python scripts/cli.py
python scripts/cli.py --single "Show campaign performance for account 1234567890"Claude Code
Place .mcp.json in your project root (already included):
{
"mcpServers": {
"google-ads": {
"type": "stdio",
"command": "python",
"args": ["-m", "ads_mcp.server"],
"env": {
"GOOGLE_ADS_CREDENTIALS": "${GOOGLE_ADS_CREDENTIALS}",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "${GOOGLE_ADS_LOGIN_CUSTOMER_ID}"
}
}
}
}Claude Code auto-discovers .mcp.json. CLAUDE.md is written specifically for Claude Code
to orient itself — it reads this first on every session.
Gemini CLI
Add to your project's .gemini/settings.json:
{
"mcpServers": {
"google-ads": {
"command": "python",
"args": ["-m", "ads_mcp.server"],
"env": {
"GOOGLE_ADS_CREDENTIALS": "/path/to/google-ads.yaml",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
}
}
}
}For the full Gemini CLI setup with Google Ads slash commands and agent skills, see gemini-cli-googleadsagent.
Remote option — if you deploy the buddy-agent on Cloudflare Workers, you can skip local credentials entirely and connect via SSE:
{
"mcpServers": {
"buddy-google-ads": {
"url": "https://your-buddy-agent.workers.dev/sse"
}
}
}OpenAI Agents SDK
from agents.mcp import MCPServerStdio
import os
server = MCPServerStdio(
command="python",
args=["-m", "ads_mcp.server"],
env={
"GOOGLE_ADS_CREDENTIALS": os.environ["GOOGLE_ADS_CREDENTIALS"],
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": os.environ.get("GOOGLE_ADS_LOGIN_CUSTOMER_ID", ""),
}
)
# All 29 Google Ads tools automatically availableTool Reference
Read Tools
list_accessible_customers · list_accounts · execute_gaql · get_campaign_performance
get_keyword_performance · get_search_terms · get_ad_performance · get_account_budget_summary
generate_keyword_ideas
Audit Tools
get_auction_insights · get_change_history · get_device_performance · get_geo_performance
get_recommendations · get_pmax_performance · get_impression_share
Write Tools (dry-run by default — requires confirm=True)
update_campaign_budget · update_campaign_status · update_ad_group_status · update_keyword_bid
add_keywords · add_negative_keywords · remove_negative_keyword · create_campaign
create_ad_group · switch_bidding_strategy · generic_mutate
Doc Tools
get_gaql_reference · get_workflow_guide
Credentials
# Option 1: google-ads.yaml path (recommended)
GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890
# Option 2: individual env vars
GOOGLE_ADS_DEVELOPER_TOKEN=...
GOOGLE_ADS_CLIENT_ID=...
GOOGLE_ADS_CLIENT_SECRET=...
GOOGLE_ADS_REFRESH_TOKEN=...
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890Full credential setup guide: google-ads-api-agent README → Step 1A
v23 Service Coverage
Google Ads API v23 has 70+ services. Current status:
✅ 29 tools implemented — core reporting, audit, write operations, doc references
🔧 42 services planned — full roadmap in
docs/SERVICES.md⬜ ~20 out of scope — platform admin, deprecated, LSA-specific
Attribution
Google LLC (Apache 2.0)
google-ads Python client library — Copyright 2023 Google LLC
https://github.com/googleads/google-ads-python
All API calls in this package use thegoogle-adspip package published by Google. The v23 service definitions, proto types, and gRPC clients are Google's work.
googleads/google-ads-mcp — https://github.com/googleads/google-ads-mcp
Patterns: MCP singleton,search_stream+field_mask.paths
google-marketing-solutions/google_ads_mcp — https://github.com/google-marketing-solutions/google_ads_mcp
Patterns: doc-serving MCP tools, remote OAuth,omit_unselected_resource_names
Community (MIT)
cohnen/mcp-google-ads — https://github.com/cohnen/mcp-google-ads
Patterns:format_valueproto serialization helper
gomarble-ai/google-ads-mcp-server — https://github.com/gomarble-ai/google-ads-mcp-server
Patterns: dual transport (stdio + HTTP), KeywordPlanIdeaService
itallstartedwithaidea/google-ads-api-agent — https://github.com/itallstartedwithaidea/google-ads-api-agent
Patterns: auction insights, change history, campaign creator, bidding strategy manager, negative keywords, geo targeting, PMax reporting, Filter-First Architecture
Full per-feature attribution table: docs/SERVICES.md
Related
google-ads-skills — Anthropic Agent Skills for Claude (analysis, audit, write, math, MCP)
google-ads-api-agent — Full Python agent with 28 API actions and 6 sub-agents
google-ads-gemini-extension — Gemini CLI extension with 22 MCP tools, skills, commands, and themes
googleadsagent.ai — Production deployment (Buddy) on Cloudflare with semantic memory, billing, and monitoring
License
MIT — see LICENSEgoogle-ads dependency: Apache 2.0, Copyright 2023 Google LLC
FastMCP: Apache 2.0
Available Tools
29 toolsadd_keywordsA
Add keywords to an ad group.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: keywords (required), ad_group_id (required), customer_id (required), confirm, +1 more. Returns: object
add_negative_keywordsA
Add negative keywords to a campaign.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: keywords (required), campaign_id (required), customer_id (required), confirm, +2 more. Returns: object
create_ad_groupA
Create a new ad group within a campaign.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: name (required), campaign_id (required), customer_id (required), status, +3 more. Returns: object
create_campaignA
Create a new campaign.
Default is DRY RUN — shows preview. Pass confirm=True to execute. New campaigns are always created PAUSED unless you explicitly set status='ENABLED'.
Inputs: name (required), customer_id (required), campaign_type (required), daily_budget_dollars (required), +9 more. Returns: object
execute_gaqlB
Execute any Google Ads Query Language (GAQL) query.
Inputs: query (required), customer_id (required), login_customer_id. Returns: data
generate_keyword_ideasB
Generate keyword ideas using the Google Ads Keyword Planner.
Inputs: keywords (required), customer_id (required), page_url, language_id, +2 more. Returns: object
generic_mutateA
Generic mutate operation for advanced use cases not covered by specific tools.
Use this when you need to modify a resource type that doesn't have a dedicated write tool. Requires understanding the Google Ads API proto structure.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: customer_id (required), resource_data (required), resource_type (required), operation_type (required), +3 more. Returns: object
get_account_budget_summaryA
Return campaign budgets and current spend for budget pacing analysis.
Returns daily budget amounts alongside 30-day cost to help identify budget-constrained campaigns or overspending.
Inputs: customer_id (required), login_customer_id. Returns: object
get_ad_performanceA
Return ad-level performance including RSA headlines and descriptions.
Useful for creative audits, A/B analysis, and identifying low-performing ad copy that should be refreshed.
Inputs: customer_id (required), days, login_customer_id. Returns: object
get_auction_insightsA
Return competitive auction insights — impression share, overlap rate, position above rate, and outranking share for competing domains.
This is the primary competitive intelligence tool. Shows where your ads appear relative to competitors in the same auctions.
Inputs: customer_id (required), days, campaign_id, login_customer_id. Returns: object
get_campaign_performanceB
Return campaign performance metrics for the last N days.
Inputs: customer_id (required), days, login_customer_id. Returns: object
get_change_historyA
Return account change history — who changed what, when, and what it changed from/to.
Invaluable for audits, debugging performance drops, and tracking unauthorized changes.
Inputs: customer_id (required), days, limit, resource_type, +1 more. Returns: object
get_device_performanceA
Return campaign performance segmented by device — MOBILE, DESKTOP, TABLET.
Use this to identify bid adjustment opportunities and diagnose mobile vs. desktop conversion rate gaps.
Inputs: customer_id (required), days, login_customer_id. Returns: object
get_gaql_referenceA
Return the GAQL (Google Ads Query Language) reference guide.
Call this before writing complex queries to ensure correct field names, operators, and resource relationships. Avoids the most common GAQL errors (wrong keyword field names, unsupported CONTAINS operator, cost field paths).
Source: google-marketing-solutions/google_ads_mcp (tools/docs.py)
Inputs: no named parameters. Returns: result
get_geo_performanceC
Return performance segmented by geographic location.
Inputs: customer_id (required), days, geo_level, login_customer_id. Returns: object
get_keyword_performanceC
Return keyword performance metrics.
Inputs: customer_id (required), days, min_impressions, login_customer_id. Returns: object
get_pmax_performanceA
Return Performance Max campaign and asset group performance.
PMax requires separate queries for campaign-level and asset-group-level data since asset groups can't be joined to standard metrics in a single query.
Inputs: customer_id (required), days, login_customer_id. Returns: object
get_recommendationsB
Return Google's optimization recommendations for the account.
Inputs: customer_id (required), login_customer_id, recommendation_type. Returns: object
get_search_termsA
Return search term performance — actual queries that triggered your ads.
Essential for SQR (Search Query Reports), finding negative keyword opportunities, and identifying new keyword candidates.
Inputs: customer_id (required), days, min_clicks, login_customer_id. Returns: object
get_workflow_guideA
Return the recommended workflow for using Google Ads MCP tools.
Provides a step-by-step guide: account discovery → currency check → data retrieval → custom queries. Good first call when starting a new analysis session.
Inputs: no named parameters. Returns: result
list_accessible_customersA
Return customer IDs directly accessible by the authenticated user.
These IDs can be used as the customer_id parameter in all other tools.
For MCC (manager) accounts, use list_accounts() to also see child accounts.
Source: googleads/google-ads-mcp (tools/core.py) — uses CustomerService.list_accessible_customers() via the Python client library (cleaner than raw REST used in repo1/repo4).
Inputs: no named parameters. Returns: result
list_accountsA
List all accessible Google Ads accounts including MCC sub-accounts.
Returns a structured dict with account metadata (id, name, is_manager, level, parent_id). For manager (MCC) accounts, sub-accounts are fetched and included up to two levels deep.
Source: gomarble-ai/google-ads-mcp-server (server.py) — MCC traversal logic; combined with repo2 CustomerService pattern for cleaner API calls.
Recommended first step: run this to discover available customer IDs before calling any reporting tools.
Inputs: no named parameters. Returns: object
remove_negative_keywordA
Remove a negative keyword by resource name.
Get the resource_name from get_search_terms or execute_gaql on campaign_criterion.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: customer_id (required), resource_name (required), confirm, login_customer_id. Returns: object
switch_bidding_strategyA
Change a campaign's bidding strategy.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: campaign_id (required), customer_id (required), new_strategy (required), confirm, +4 more. Returns: object
update_ad_group_statusA
Pause or enable an ad group.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: status (required), ad_group_id (required), customer_id (required), confirm, +1 more. Returns: object
update_campaign_budgetA
Update a campaign's daily budget.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: campaign_id (required), customer_id (required), new_daily_budget_dollars (required), confirm, +1 more. Returns: object
update_campaign_statusA
Pause or enable a campaign.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: status (required), campaign_id (required), customer_id (required), confirm, +1 more. Returns: object
update_keyword_bidA
Update the CPC bid for a specific keyword.
Default is DRY RUN — shows preview. Pass confirm=True to execute.
Inputs: ad_group_id (required), customer_id (required), criterion_id (required), cpc_bid_dollars (required), +2 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 29 tools
Most tools have clearly distinct targets (e.g., get_campaign_performance vs get_keyword_performance vs get_ad_performance). Two potential confusions exist: list_accessible_customers vs list_accounts (similar but descriptions distinguish them), and execute_gaql/generic_mutate overlap with all specific tools as catch-alls, but they are clearly labeled as advanced/fallback.
The naming pattern is predominantly verb_noun (list_, get_, update_, add_, create_). Minor inconsistencies: remove_negative_keyword is singular while add_negative_keywords is plural, and switch_bidding_strategy, generate_keyword_ideas, execute_gaql, generic_mutate don't follow the same verb family, but the overall style is readable and predictable.
29 tools is on the heavy side, but the Google Ads domain is broad, covering account discovery, performance reporting, insights, and mutations. Some tools are arguably redundant (get_gaql_reference, get_workflow_guide are documentation helpers, and generic_mutate covers many cases), making the set slightly bloated but not extreme.
The surface covers many important operations: listing accounts, retrieving performance across dimensions, search terms, auction insights, change history, recommendations, keyword planning, and several mutation tools (create campaign/ad group, update budgets/status/bids, add/remove keywords). However, notable gaps exist: no direct tools for listing/creating ads (e.g., responsive search ads), no ad group retrieval, and no comprehensive campaign list tool (only via GAQL or performance queries). The generic tools mitigate these gaps but imply workarounds.
Maintenance
Related MCP Connectors
Google Ads MCP server — manage campaigns, keywords, and metrics.
Google Ads MCP server: 17 tools for reporting, campaigns, keywords, assets. Writes preview first.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Meta Ads MCP server with 47 tools for campaigns, creatives, audiences, and insights.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for Google Ads API — 22 tools for campaigns, keywords, RSAs, assets, audiences, geo/device performance, impression share, auction insights, and budget pacing. Community edition with B2B/agency-focused tooling beyond the official Google MCP.221MIT

google-ads-mcpofficial
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
- AlicenseNot gradedqualityBmaintenanceMCP server for Google Ads API with built-in safeguards, MCC support, and 36 tools for campaign management, reporting, and optimization.460 npm1MIT