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 + the OAuth client
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

41 read-only tools, grouped:

• Accounts (5) — account discovery, metadata, conversion actions, labels
• Reporting (24) — campaigns, ad groups, keywords, search terms, geo / device / demographic segments, Performance Max assets
• Diagnostics (9) — Quality Score, ad extensions, bid strategies, budget pacing, change history, negative keywords, impression share
• Query (2) — raw GAQL SELECT + a structured GAQL builder
• Metadata (1) — 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 mint your refresh token.

This project ships no credentials and no hosted service. You bring your own Google Cloud project, OAuth client, and developer 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

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 (incl. a Windows helper): 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 (teams)

To host one 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 authenticates users via an OAuth proxy (one-click connect from Claude.ai, no pasted secrets) and forwards each user's token to the Ads API.

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 uses FastMCP's Google OAuth proxy. Each request carries a per-user Google token (with the adwords scope) that is forwarded to the Google Ads API, so authorization is whatever that user's Google account can do. The server stores no user credentials — only the operator's developer token and the OAuth client_id/secret.

---

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.