Skip to main content
Glama
mcp-google-ads

mcp-google-ads

by apexradius

mcp-google-ads

Multi-account Google Ads MCP server for operators who need one MCP surface across multiple client or in-house ad accounts without restarting the server.

Release posture: beta package, version 0.1.0 from pyproject.toml.

Choose your path

You are...

Start here

Then

Connecting the server to your MCP client

docs/start-here.md

Quick start below

Auditing account switching and retries

docs/architecture.md

gads/server.py

Reviewing packaging metadata

pyproject.toml

accounts.example.json

Related MCP server: Google Ads MCP Server

Architecture

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> S[FastMCP server]
  S --> M[Account manager]
  M --> F[Accounts config]
  S --> Q[GAQL query helpers]
  Q --> R[Retry wrapper]
  R --> A[Google Ads API]
  A --> R --> S

Request flow

flowchart TD
  P[Operator asks for account or campaign data] --> T[Selected MCP tool]
  T --> A[Resolve named or default account]
  A --> B[Build Google Ads client]
  B --> C[Run GAQL query]
  C --> D{API call succeeds?}
  D -- yes --> E[Normalize rows and return]
  D -- retryable --> F[Backoff and retry]
  F --> D
  D -- no --> G[Return error payload]

Quick start

  1. Install the package.

python -m pip install mcp-google-ads-multi
  1. Copy the accounts config template and add your accounts.

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json
  1. Register it in your MCP client.

{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["mcp-google-ads-multi"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
      }
    }
  }
}

Available tools

Tool group

Tools

Purpose

Account selection

list_accounts, set_default_account, list_customers

Manage account routing and discover accessible customers

Spend summary

get_account_summary, compare_periods

Period-over-period account reporting

Campaign analysis

list_campaigns, get_campaign_performance

Campaign inventory and range-based metrics

Query-level detail

get_keyword_performance, search_terms_report, get_ad_performance

Keyword, search-term, and ad reporting

Runtime proof

Claim

Proof

Package entry point is stable

mcp-google-ads-multi = "gads.server:main" in pyproject.toml

Multi-account routing is first-class

AccountManager() and set_default_account() in gads/server.py

Queries go through reusable helpers

gads/query.py and gads/retry.py

Config is file-driven

accounts.example.json documents the accounts shape

Repo map

Path

Purpose

gads/server.py

FastMCP tool surface

gads/accounts.py

Account config, OAuth/service-account loading

gads/query.py

GAQL execution helpers

gads/retry.py

Retry behavior for API calls

docs/start-here.md

Setup, validation, common failures

docs/architecture.md

Component map and request lifecycle

Validation

Check

Command

Import compiles

python -m compileall gads

Package builds

python -m build

README/docs links are local

rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

License

MIT

Project context for new tasks

Use INDEX.md to find task-specific contracts; consult prompt.md when product direction is relevant. Historical examples do not select the current task.

Available Tools

10 tools
compare_periodsC

Compare performance between two date ranges.

Inputs: customer_id (required), period1_end (required), period2_end (required), period1_start (required), +3 more. Returns: object

get_account_summaryB

Get top-level spend and conversion totals for an account.

Inputs: end_date (required), start_date (required), customer_id (required), account. Returns: object

get_ad_performanceB

Get ad-level performance (headlines, descriptions, CTR, conversions).

Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result

get_campaign_performanceC

Get campaign performance metrics for a date range.

Inputs: end_date (required), start_date (required), customer_id (required), account, +1 more. Returns: result

get_keyword_performanceA

Get keyword-level performance including quality scores.

Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result

list_accountsB

List all configured Google Ads accounts and which is the current default.

Inputs: no named parameters. Returns: result

list_campaignsC

List campaigns for an account.

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

list_customersA

List all accessible Google Ads customer accounts.

If customer_id is provided, lists child accounts under that MCC. Otherwise lists all accessible accounts for this login.

Inputs: account, customer_id. Returns: result

search_terms_reportB

Get actual search terms that triggered your ads.

Inputs: end_date (required), start_date (required), customer_id (required), account, +2 more. Returns: result

set_default_accountA

Set the default account used when no account is specified in other tools.

Inputs: account (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools are clearly distinct by entity (accounts, campaigns, keywords, ads) and action (list, get, set, compare). However, list_accounts and list_customers both list accounts with subtle differences (configured vs accessible) that could cause confusion.

    Naming Consistency4/5

    Tool names predominantly follow a verb_noun pattern (list_*, get_*, set_*). The deviations are 'compare_periods' (verb_noun but not get/list) and 'search_terms_report' (noun phrase without a verb), but the overall pattern is still readable and predictable.

    Tool Count5/5

    Ten tools is well within the ideal range for a domain-specific server. Each tool covers a distinct aspect of Google Ads reporting and account management, and none feel redundant or excessive.

    Completeness4/5

    The server provides comprehensive read/reporting coverage: account listing, summaries, campaign/keyword/ad performance, search terms, and period comparison. It lacks management operations like creating or updating campaigns, but this seems intentionally scoped to analytics and account selection, so the gaps are minor.

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables authorized users to securely connect to and manage their Google Ads accounts through MCP clients, with support for campaigns, ad groups, ads, keywords, reporting, and billing. Runs as a remote multi-user server on Cloudflare Workers with per-user authentication and safety controls.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing Google Ads campaigns through the official Google Ads API, covering accounts, campaigns, budgets, keywords, search terms, and keyword ideas. It provides tools for both reading and mutating live ads data, such as pausing campaigns, updating budgets, and adding keywords.
      MIT