public-google-ads-mcp

Google Ads MCP Server

A Model Context Protocol server that gives an LLM (Claude, Copilot, …) read-only access to Google Ads account data – campaigns, ad groups, keywords, search terms, segmented performance reports, bidding, budgets, conversions, Performance Max assets, labels, change history, impression share, plus an ad-hoc GAQL escape hatch.

It is a thin wrapper over Google Ads' GAQL search_stream API. Every tool takes a customer_id per request, so one running server can query any account the authenticated credentials can reach.

Two ways to run

	Local (stdio)	Remote (HTTP + OAuth)
Who it's for	An individual on their own machine	A team sharing one hosted instance
Auth to Google Ads	Your own refresh-token credentials	Each user signs in with their own Google account; their token is forwarded to the Ads API, so they only see accounts they personally can access
The server holds	Your full credentials	Only the developer token (no OAuth secret)
Clients	Claude Desktop, VS Code/Copilot, any stdio MCP client	Claude.ai web connector, Claude Desktop/Code
Setup	This README, below	docs/REMOTE_DEPLOY.md

Most people want Local. Start there.

What it does

Read-only tools, grouped:

• Accounts – account discovery, metadata, conversion actions, labels
• Reporting – campaigns, ad groups, keywords, search terms, geo / device / demographic segments, Performance Max assets
• Diagnostics – Quality Score, ad extensions, bid strategies, budget pacing, change history, negative keywords, impression share
• Query – raw GAQL SELECT + a structured GAQL builder
• Metadata – selectable / filterable / sortable fields per GAQL resource

Full catalog with per-tool descriptions: docs/TOOLS.md.

---

Prerequisites

• uv – Python package/runtime manager.
• A Google Cloud project with the Google Ads API enabled.
• A Google Ads developer token (how to get one).
• An OAuth 2.0 client in that project (Desktop or Web type) – used to generate your refresh token.

---

Local setup (stdio)

1. Clone and install

git clone https://github.com/VidenGrowth/public-google-ads-mcp google-ads-mcp
cd google-ads-mcp
uv sync

2. Configure credentials

cp .env.example .env
# edit .env (e.g. `nano .env`) and fill in your credentials

Fill in (see .env.example for the full list):

• GOOGLE_ADS_DEVELOPER_TOKEN
• GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET
• GOOGLE_ADS_REFRESH_TOKEN (generate it in the next step)
• GOOGLE_ADS_LOGIN_CUSTOMER_ID (optional – only when operating through a manager/MCC account; digits, no dashes)

The target customer_id is not in .env; the agent passes it per request.

3. Generate a refresh token

uv run auth/generate_refresh_token.py -c client_secret.json

Sign in with a Google account that can access the Ads accounts you want, then paste the printed token into .env as GOOGLE_ADS_REFRESH_TOKEN. Full walkthrough: auth/README.md.

4. Test locally

uv run python scripts/smoke_test.py

Expected: ✓ server wired up – 41 tools registered, followed by get_accessible_accounts returning your accounts. If credentials are missing you'll get a clear <error>{"error":"Google Ads client not configured. …"}</error> instead – fix .env and re-run.

Run the test suite anytime with:

uv run --with pytest pytest tests/ -q

5. Connect a client

Claude Desktop (claude_desktop_config.json – macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/google-ads-mcp", "run", "google-ads-mcp"]
    }
  }
}

Restart Claude Desktop fully (quit from the tray/menu, not just close the window).

Then enable Chat > MCP in settings, run MCP: Start Server from the Command

---

Example prompts

Once connected, try (replace the ID with one of your accounts):

• "Show me all campaigns for customer 1234567890"
• "Find wasted spend in search terms for customer 1234567890"
• "Which keywords have quality scores below 5 for customer 1234567890?"
• "Compare device and geographic performance for customer 1234567890 over the last 30 days"
• "Show the age + gender breakdown for customer 1234567890"
• "Is customer 1234567890 on pace to spend its budget this month?"

Parameter conventions (date ranges, ID/name filters, status filters, sorting) are documented in docs/TOOLS_DESIGN.md.

---

Remote deploy

To host shared instance where each teammate signs in with their own Google account – no per-user install, and everyone only sees the Ads accounts they can access – deploy the HTTP transport with Google OAuth. The server is a pure OAuth Resource Server: the MCP client signs the user in with Google, and the server verifies each request's token and forwards it to the Ads API. It holds only the developer token – no OAuth client secret.

Full guide: docs/REMOTE_DEPLOY.md.

---

How authentication works

• Local (stdio): the server uses your refresh-token credentials. There is no MCP-layer auth – the server runs on your machine under your control.
• Remote (HTTP): the server is an OAuth 2.0 Resource Server (RFC 9728). The MCP client obtains a Google token directly (Google's own OAuth flow), and the server verifies each request's token – checking the aud claim and the adwords scope – then forwards it to the Google Ads API. Authorization is whatever that user's Google account can do. The server runs no OAuth flow and stores no secret beyond the operator's developer token; the OAuth client secret lives in the connector config, not on the server.

---

Architecture

See docs/PROJECT_MAP.md for a directory tour and request flow, and docs/TOOLS_DESIGN.md for the design conventions every tool follows.

License

MIT.