Skip to main content
Glama
google-ads-mcp

google-ads-mcp

by samtactical

google-ads-mcp

A read-only MCP server for the Google Ads API. It exposes reporting tools (campaigns, ad groups, keywords, and raw GAQL queries) so an MCP client (Claude Code, Claude Desktop, etc.) can query your Google Ads account. There are no mutate/write tools — this server cannot change campaigns, budgets, or bids.

Tools

Tool

Description

list_accessible_customers

List customer IDs accessible to the configured credentials.

get_account_hierarchy

List accounts under a manager (MCC) account.

list_campaigns

List campaigns and their settings (no metrics).

get_campaign_performance

Campaign-level metrics (impressions, clicks, cost, conversions).

get_ad_group_performance

Ad group-level metrics.

get_keyword_performance

Keyword-level metrics.

run_gaql

Run a raw read-only GAQL SELECT query.

Related MCP server: Google Ads MCP Reader

Prerequisites

You need Google Ads API credentials:

  1. A developer token from the Google Ads API Center (Tools & Settings → API Center) on the manager account you'll authenticate with.

  2. An OAuth2 client ID / client secret from a Google Cloud project with the Google Ads API enabled.

  3. A refresh token for a user with access to the target account(s). See Google's OAuth desktop flow guide or run the helper script bundled with the google-ads Python library.

  4. If you authenticate via a manager (MCC) account on behalf of a client account, its login_customer_id.

Setup

# from the repo root
pip install -e .

Configure credentials one of two ways:

Option A: YAML file

cp google-ads.yaml.example google-ads.yaml
# edit google-ads.yaml with your values

Option B: environment variables

cp .env.example .env
# edit .env, then export the variables into your shell environment

Either google-ads.yaml in the current directory, or the GOOGLE_ADS_* environment variables, will be picked up automatically. Set GOOGLE_ADS_CONFIGURATION_FILE_PATH to point at a YAML file in a different location if you'd prefer.

Running standalone

python -m google_ads_mcp
# or, after `pip install -e .`:
google-ads-mcp

The server communicates over stdio, per the MCP spec.

Registering with an MCP client

Claude Code (project-level .mcp.json, or claude mcp add):

{
  "mcpServers": {
    "google-ads": {
      "command": "google-ads-mcp",
      "env": {
        "GOOGLE_ADS_CONFIGURATION_FILE_PATH": "/absolute/path/to/google-ads.yaml"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json): same mcpServers entry as above.

Security notes

  • This server only issues GAQL SELECT queries via GoogleAdsService.SearchStream. GAQL has no INSERT/UPDATE/DELETE syntax, so there is no way to mutate Google Ads data through these tools.

  • Never commit google-ads.yaml or .env — both are gitignored. Treat your developer token, OAuth client secret, and refresh token as credentials.

  • customer_id and entity IDs are validated as numeric before being interpolated into GAQL query strings.

Available Tools

7 tools
get_account_hierarchyB

List the accounts under a Google Ads manager (MCC) account, including nesting level.

Args: customer_id: The manager account's customer ID (10 digits, dashes optional).

Inputs: customer_id (required). Returns: result

get_ad_group_performanceA

Get ad group-level performance metrics (impressions, clicks, cost, conversions).

Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.

Inputs: customer_id (required), date_range, campaign_id. Returns: result

get_campaign_performanceA

Get campaign-level performance metrics (impressions, clicks, cost, conversions).

Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.

Inputs: customer_id (required), date_range, campaign_id. Returns: result

get_keyword_performanceA

Get keyword-level performance metrics (impressions, clicks, cost, conversions).

Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.

Inputs: customer_id (required), date_range, campaign_id. Returns: result

list_accessible_customersA

List the Google Ads customer IDs directly accessible to the configured credentials.

Inputs: no named parameters. Returns: result

list_campaignsA

List campaigns in an account with their basic settings (no performance metrics).

Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). status: Optional filter - one of ENABLED, PAUSED, REMOVED.

Inputs: customer_id (required), status. Returns: result

run_gaqlA

Run a raw read-only GAQL SELECT query against the Google Ads API.

Use this for reporting needs not covered by the other tools. GAQL only supports SELECT statements, so this cannot modify any Google Ads data.

Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). query: A GAQL SELECT query, e.g. "SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED'".

Inputs: query (required), customer_id (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: account listing, hierarchy, campaign listing, and performance at campaign, ad group, and keyword levels, plus a raw query fallback. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (list_, get_, run_) and use snake_case throughout. The verbs accurately reflect the operation, and the nouns clearly indicate the target resource.

    Tool Count5/5

    With 7 tools, the server is well-scoped for a read-only Google Ads reporting use case. Each tool serves a clear purpose, and the count is neither too sparse nor overwhelming.

    Completeness4/5

    The surface covers account enumeration, hierarchy, campaign listing, and performance at three key levels, plus a generic GAQL escape hatch. Minor gaps like structured ad group or keyword listing exist, but run_gaql can fill them, so no dead ends remain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only access to Google Ads account data including campaigns, ad groups, keywords, and performance reports. Enables querying via GAQL through an MCP interface.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server for querying Google Ads data using GAQL, enabling AI assistants to safely read campaign performance, ad groups, and keywords.
      12
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to Google Analytics 4 and Google Search Console data, allowing users to run reports, query search analytics, and generate combined snapshots for reporting.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only inspection of Google Ads accounts through MCP, including account inventory, reporting, metadata, change history, and safe GAQL queries.
      Apache 2.0