Skip to main content
Glama
tolkozin

Google Ads MCP

by tolkozin
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python

Google Ads MCP

An MCP server that lets an LLM agent operate Google Ads — both Search and App/UAC campaigns. It exposes read tools (GAQL) always, and guarded write tools behind a mutation flag.

Status: Phase 1 — reads only (list_accessible_customers, search, describe_resource). Writes (budgets, campaigns, ad groups, keywords, ads, UAC) land in later phases behind ADS_MCP_ENABLE_MUTATIONS.

Design principles: every change will be reversible, confirmable, account- and budget-scoped. Reads are always safe.

Requirements

  • Python 3.12+

  • uv (curl -LsSf https://astral.sh/uv/install.sh | sh)

  • A Google Ads developer token, an OAuth2 client, and a refresh token.

  • Google Ads API version is pinned to v23 in src/google_ads_mcp/config.py.

Related MCP server: Google Ads API v20 MCP Server

Install

uv sync --extra dev

Getting credentials

You need five values in a google-ads.yaml file (copy from google-ads.yaml.example).

  1. developer_token — Google Ads UI → Tools → API Center. Basic Access is enough (15k operations/day).

  2. OAuth client (client_id, client_secret) — Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → Desktop app. Enable the Google Ads API for the project first.

  3. refresh_token — generate once with the OAuth consent flow for scope https://www.googleapis.com/auth/adwords. The official google-ads-python repo ships generate_user_credentials.py for exactly this; run it with your client id/secret and paste the resulting refresh token.

  4. login_customer_id — your manager (MCC) account id without dashes. Omit if you authenticate directly against a single account.

Then:

cp google-ads.yaml.example google-ads.yaml   # fill in real values (gitignored)
cp .env.example .env                          # set GOOGLE_ADS_CREDENTIALS to its path
export GOOGLE_ADS_CREDENTIALS="$PWD/google-ads.yaml"

Secrets are never committed. google-ads.yaml, .env, and *.audit.jsonl are gitignored.

Run

# stdio (default — what Claude Desktop uses)
uv run google-ads-mcp

# or HTTP (future Cloud Run hosting)
ADS_MCP_HTTP=true uv run google-ads-mcp

Connect to Claude Desktop

Edit Claude Desktop's config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add an entry (use absolute paths):

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Google Ads MCP",
        "run",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "/absolute/path/to/Google Ads MCP/google-ads.yaml"
      }
    }
  }
}

If uv isn't on Claude Desktop's PATH, use its absolute path (which uv). Restart Claude Desktop. The three read tools appear under the 🔌 connector menu.

First check

Ask Claude: "List my accessible Google Ads customers", then "Run this GAQL on account : SELECT campaign.id, campaign.name, campaign.status FROM campaign LIMIT 10".

Tools (Phase 1)

Tool

Description

list_accessible_customers()

Customer ids the auth user can access.

search(customer_id, gaql, page_size=1000)

Execute a GAQL query.

describe_resource(resource)

Discover selectable/filterable fields for GAQL.

All return a unified envelope: {status, dry_run, resource_name, diff, message, data}.

Safety flags (parsed now, enforced from Phase 2)

Env var

Default

Purpose

ADS_MCP_ENABLE_MUTATIONS

false

Master switch for all write tools.

GOOGLE_ADS_ALLOWED_CUSTOMER_IDS

(empty)

CSV allowlist of customer ids.

GOOGLE_ADS_MAX_DAILY_BUDGET_USD

100

Budget/bid ceiling without override.

GOOGLE_ADS_DEFAULT_VALIDATE_ONLY

true

Mutations dry-run by default.

GOOGLE_ADS_AUDIT_LOG

./google-ads.audit.jsonl

Applied-change log.

Security model

  • Secrets never enter git. google-ads.yaml, .env, and *.audit.jsonl are gitignored. The repo ships only *.example files with placeholders. Account ids and app ids in tests are fake.

  • Writes are off by default (ADS_MCP_ENABLE_MUTATIONS=false).

  • Allowlist — mutations are refused for any account outside GOOGLE_ADS_ALLOWED_CUSTOMER_IDS. Reads are unaffected.

  • Budget cap — a budget/bid above GOOGLE_ADS_MAX_DAILY_BUDGET_USD is refused unless the call passes override=true.

  • Two-key apply — a real change needs BOTH validate_only=false AND confirm=true. Otherwise the tool returns the diff (validate_only) or a preview, applying nothing.

  • New campaigns/ad groups/ads are created PAUSED — nothing serves until you deliberately enable it.

  • Audit log — every applied change (and every failure during apply) is appended to the JSONL audit log; dry-runs are not logged as applied.

  • Atomic batches — multi-operation tools (manage_keywords, manage_negative_keywords) are all-or-nothing by design (no partial_failure), so a batch never half-applies.

If a credential is ever exposed, rotate it: developer token in the Ads API Center, OAuth client secret in Google Cloud Console → Credentials.

Tests

uv run pytest          # offline tests (no network); live calls need real creds

Roadmap

  1. ✅ Skeleton + reads.

  2. ✅ Safety layer (validate_only wrapper, allowlist, budget guard, confirm, audit, error mapping) — see safety.py, audit.py, tests/test_guardrails.py.

  3. ✅ Search writes (budget → campaign → ad group → keywords/negatives → RSA → statuses) — writes_common.py, writes_search.py. New campaigns/ad groups/ads are created PAUSED; live validate_only verified.

  4. ✅ UAC writes (app campaign, app assets, target updates) — writes_app.py. App campaigns created PAUSED; create_app_campaign structurally validated against the live API. Real apply + manage_app_assets verify on the final account (where the app is provisioned).

  5. ✅ Hardening + packaging (green pytest suite, security model documented, secret scan, optional HTTP transport for Cloud Run).

Available Tools

3 tools
describe_resourceA

Discover selectable/filterable fields of a resource to help build GAQL.

Args: resource: A resource/metric/segment prefix, e.g. 'campaign', 'ad_group', 'metrics', 'segments'.

ParametersJSON Schema
NameRequiredDescriptionDefault
resourceYes

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It states the tool 'discovers' fields, implying a read-only operation, and mentions it helps build GAQL. However, it does not elaborate on side effects, permissions, rate limits, or response format. The description is minimal but sufficient for a simple introspection tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences plus an args section. It immediately states the purpose and then explains the parameter. Every sentence adds value, with no fluff. It is well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the purpose and parameter details. It does not describe return values, but for a discovery tool, the context is largely complete. Sibling tools are distinct, so no extra differentiation needed. A slightly richer description of output would improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must compensate. It does so effectively by explaining the parameter 'resource' as 'A resource/metric/segment prefix, e.g. 'campaign', 'ad_group', 'metrics', 'segments.' This adds concrete examples and context beyond the schema's type and title, making the parameter's meaning clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Discover selectable/filterable fields of a resource to help build GAQL.' It uses a specific verb ('Discover') and resource ('fields of a resource'). The tool name 'describe_resource' matches the purpose, and sibling tools (list_accessible_customers, search) are distinct, making the tool's role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool: 'to help build GAQL' and provides example resource prefixes. It does not explicitly exclude other tools or state when not to use it, but given the distinct siblings (search for executing queries, list_accessible_customers for listing customers), the usage context is fairly clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accessible_customersA

List Google Ads customer ids the authenticated user can access.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description correctly indicates a read operation ('list'), but does not disclose potential behaviors such as pagination, rate limits, or error cases. For a parameterless tool, the transparency is acceptable but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no unnecessary words. It is front-loaded with the action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description is nearly complete. It could mention the return type (a list), but the purpose is clear. The simplicity justifies a slight deduction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters with 100% coverage. The description adds no parameter details, which is appropriate since there are none. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action ('List'), the resource ('Google Ads customer ids'), and the context ('the authenticated user can access'). It clearly distinguishes from sibling tools 'search' and 'describe_resource'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (to get a list of accessible customers), but provides no explicit guidance on when not to use it or alternatives. Given the simplicity and distinct sibling names, the implied usage is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observeddescribe_resource
    • First observedlist_accessible_customers
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: listing accessible customers, running GAQL queries, and describing resource fields. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_accessible_customers, search, describe_resource. Clear and predictable.

Tool Count4/5

Three tools is on the lower end but still within the reasonable range for a focused query interface. The count is appropriate for the server's stated purpose.

Completeness3/5

The tools cover listing accounts and querying data, but lack create, update, or delete operations for Google Ads resources. This is a notable gap for a full API surface.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Google Ads MCP Server

    johnoconnor0
    A
    license
    B
    quality
    B
    maintenance
    Enables comprehensive Google Ads campaign management and analysis through natural language, including performance metrics, keyword optimization, budget management, and custom GAQL queries.
    100
    13
    MIT

  • Google Ads API v20 MCP Server

    DigitalRocket-biz
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides comprehensive access to Google Ads API v20, enabling AI assistants to manage campaigns, accounts, assets, and reporting through natural language. It features automatic retry logic, GAQL query support, and advanced functionality for Performance Max and Demand Gen campaigns.
    11
    MIT

  • Google Ads MCP Server (Fork

    mathiaschu
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI assistants to manage Google Ads accounts by providing tools for querying account data and performing write operations such as updating campaign budgets, statuses, and bidding strategies.
    2
    -