Skip to main content
Glama
google-ads-mcp

google-ads-mcp

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

.mcp.json in project root (included)

Claude Desktop

stdio

claude_desktop_config.example.json

Cursor / Windsurf

stdio

Settings → MCP → python -m ads_mcp.server

OpenAI Agents SDK

stdio

MCPServerStdio(command="python", args=["-m", "ads_mcp.server"])

LangChain

stdio

langchain-mcp-adapters

Remote / Cloud

HTTP SSE

python -m ads_mcp.server --http


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 available

Tool 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-7890

Full 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 the google-ads pip 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_value proto 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



License

MIT — see LICENSE
google-ads dependency: Apache 2.0, Copyright 2023 Google LLC
FastMCP: Apache 2.0


googleadsagent.ai · Google Ads API Docs · MCP Spec

Available Tools

29 tools
add_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_impression_shareA

Return search impression share and lost IS reasons by campaign.

Shows what % of eligible impressions you're winning and whether you're losing to budget constraints or ad rank. Critical for scaling decisions.

Inputs: customer_id (required), days, 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

    A3.5/5.0

    Scored across 29 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      22
      1
      MIT
    • A
      license
      B
      quality
      A
      maintenance
      MCP server that provides tools and resources for interacting with Google Ads API, enabling search, metadata retrieval, and account management through natural language.
      7
      6,732 PyPI
      1,193
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Google Ads API with built-in safeguards, MCC support, and 36 tools for campaign management, reporting, and optimization.
      460 npm
      1
      MIT