googleads/google-ads-mcp

What it is

This is a Model Context Protocol server that connects AI agents and LLM clients to the Google Ads API. Agents can query accounts with GAQL, inspect resource metadata, list accessible customers, and manage labels and assets through a controlled tool interface rather than raw API calls.

Read tools include search, get_resource_metadata, and list_accessible_customers. Write tools cover create_asset, upload_video_asset, manage_labels, and manage_label_associations. The server also exposes resources such as the API discovery document, metrics, segments, and release notes so the model can learn the API surface before querying.

Mutating tools use a two-step Propose & Confirm workflow: the first call validates without committing and returns change items plus a checksum; the second call must repeat the same parameters and customer ID with that checksum. Missing or mismatched checksums are rejected before anything is changed.

Getting started

Prepare a Google Cloud project, enable the Google Ads API, and obtain credentials with the https://www.googleapis.com/auth/adwords scope, either through Application Default Credentials, a FastMCP OAuth proxy, or an existing google-ads.yaml.

Run the server with pipx, pinning a published version when available:

pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp

Then register it in your MCP client. A typical stdio configuration points at the same pipx command and passes the credentials path and project ID:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

After restarting the client, ask a question such as "what customers do I have access to?" or "How many active campaigns do I have?" Most prompts require a customer ID, which can be supplied in the prompt or defaulted through GOOGLE_ADS_LOGIN_CUSTOMER_ID for manager accounts.

For web-service deployments, set the OAuth proxy environment variables; the server then switches from stdio to streamable HTTP and is reachable at an endpoint like http://localhost:8080/mcp. Antigravity clients need the serverUrl key, while Codex can be registered with codex mcp add google_ads --url http://localhost:8080/mcp. A Dockerfile and Quadlet example support rootless Podman deployments, and the README covers Cloud Run deployment with Firestore or Redis token storage.

Configuration and limits

The bundled tools_config.yaml enables all tools by default. To run read-only, disable the labels and assets namespaces. A custom config is resolved from GOOGLE_ADS_MCP_TOOLS_CONFIG, then the working directory, then the package default; an explicitly requested but missing or invalid file stops the server from starting.

Local file features are restricted: image_asset_path and upload_video_asset only work in local stdio mode, while remote HTTP deployments need base64 image_asset_data. Connecting an agent exposes Google Ads account data to that model or client. The README notes that an extra usage-data header is added to API calls.

Firestore OAuth storage does not expire entries automatically, so long-running deployments need a cleanup job; Redis expires entries itself. The project is Apache-2.0 licensed.

HotRepo's take

The repository appeared on the Python daily list for 2026-11-11 at position 12 with 9 stars gained, reaching 1,149 stars and 362 forks overall. That is a single recorded snapshot rather than a sustained trend, but the fork count relative to stars suggests people are actively trying to integrate it, which fits an official publisher-backed MCP adapter for an existing ad platform API. The Propose & Confirm checksum design and the explicit read-only configuration are the most practical choices for teams that want an agent to inspect ads data without letting it mutate accounts freely.

Project source and documentation