Google Ads MCP Server Setup for Claude and Gemini

What the MCP Server Is (and Is Not)

Model Context Protocol (MCP) is an open standard for exposing tools to LLM clients. The Google Ads MCP server is the official Google implementation of that standard for the Google Ads API. Understanding its scope is the first thing that saves you a week:

Prerequisites and Credentials

Before you touch pipx, line up four things:

OAuth vs. Service Account

Pick this before you install. Changing auth mode later means reissuing credentials and reconfiguring every client.

Installation via pipx

The official repo is built around a single pipx command. pipx isolates the server in its own virtual environment, so it will not collide with the Python you use for client work.

1. Install pipx

# macOS / Linux
brew install pipx   # macOS
python3 -m pip install --user pipx && python3 -m pipx ensurepath   # Linux

# Verify
pipx --version

2. Dry-run the server

# Fetches the repo, installs in an isolated venv, prints the help text
pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp --help

3. Set the three environment variables

The server reads three env vars. These typically live in your shell profile or (better) a .env the MCP client injects:

export GOOGLE_APPLICATION_CREDENTIALS="/abs/path/to/credentials.json"
export GOOGLE_PROJECT_ID="your-gcp-project-id"
export GOOGLE_ADS_DEVELOPER_TOKEN="22-char-token"

Never commit these to source control. For team deploys, keep them in the client's secret manager (GCP Secret Manager, Doppler, 1Password CLI, AWS Secrets Manager) and render them into the environment at start.

Client Configuration Matrix

Same server, different config file per client. The block below appears in each.

Canonical config block

{
  "mcpServers": {
    "google-ads": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/abs/path/to/credentials.json",
        "GOOGLE_PROJECT_ID": "your-gcp-project-id",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "22-char-token"
      }
    }
  }
}

Tool Reference

The entire agent surface is two tools. Memorize them.

12-Prompt GAQL Library

These are the twelve GAQL queries our team uses 80% of the time in agency reporting. Save them as skills, prompts, or snippets for your MCP client of choice.

1. Campaign performance, last 7 days

SELECT campaign.id, campaign.name,
  metrics.cost_micros, metrics.conversions, metrics.ctr
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.cost_micros DESC

2. Search terms with zero conversions

SELECT search_term_view.search_term, metrics.cost_micros, metrics.clicks
FROM search_term_view
WHERE metrics.conversions = 0
  AND metrics.cost_micros > 50000000
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
LIMIT 100

3. Frequency saturation (v23.1)

SELECT campaign.id, campaign.name,
  metrics.unique_users, metrics.unique_users_ten_plus
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
  AND campaign.advertising_channel_type = 'PERFORMANCE_MAX'

4. Ad groups with no ads served

SELECT ad_group.name, ad_group.status, metrics.impressions
FROM ad_group
WHERE metrics.impressions = 0
  AND ad_group.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS

5. Budget pacing

SELECT campaign.name, campaign_budget.amount_micros,
  metrics.cost_micros
FROM campaign
WHERE segments.date = TODAY
  AND campaign.status = 'ENABLED'

6. Top converting keywords

SELECT ad_group_criterion.keyword.text, metrics.conversions,
  metrics.cost_per_conversion
FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions > 0
ORDER BY metrics.conversions DESC
LIMIT 50

7. Disapproved assets

SELECT ad_group_ad.ad.id, ad_group_ad.policy_summary.approval_status
FROM ad_group_ad
WHERE ad_group_ad.policy_summary.approval_status
  IN ('DISAPPROVED', 'SITE_SUSPENDED')

8. Device-split conversion rate

SELECT segments.device, metrics.conversions, metrics.clicks,
  metrics.conversions_value
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
GROUP BY segments.device

9. Quality score distribution

SELECT ad_group_criterion.quality_info.quality_score,
  COUNT(*) AS count
FROM keyword_view
WHERE ad_group_criterion.status = 'ENABLED'
GROUP BY ad_group_criterion.quality_info.quality_score

10. Impression share lost to budget

SELECT campaign.name,
  metrics.search_budget_lost_impression_share,
  metrics.search_rank_lost_impression_share
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.search_budget_lost_impression_share DESC

11. Geographic performance

SELECT geographic_view.country_criterion_id,
  metrics.conversions, metrics.cost_micros
FROM geographic_view
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.conversions DESC
LIMIT 20

12. Asset group performance (Performance Max)

SELECT asset_group.name, metrics.impressions, metrics.conversions,
  metrics.cost_per_conversion
FROM asset_group
WHERE segments.date DURING LAST_14_DAYS
ORDER BY metrics.conversions DESC

Agent Workflow Patterns

Three patterns work cleanly with the read-only MCP server:

Security Hardening

The read-only constraint removes write risk but not read risk. Five hardening rules we apply on every agency deploy:

• Scope credentials narrowly. One service account per client; grant only the customer IDs that client touches.
• Never commit secrets. credentials.json, developer tokens, and refresh tokens go in a secret manager (GCP Secret Manager, Doppler, 1Password CLI). .env is gitignored.
• Pin the server version. Replace git+https://.../google-ads-mcp.git with git+https://.../google-ads-mcp.git@<commit-sha> so an upstream change never silently alters behaviour.
• Log every query. Wrap the MCP call site in audit logging that records user, customer_id, GAQL, row count. Compliance-friendly and invaluable for debugging.
• Rotate keys quarterly. Service-account JSON keys live as long as you let them. Calendar a quarterly rotation.

Common Errors and Fixes

Conclusion

The Google Ads MCP server is the smallest possible surface area for an enormous capability: a natural-language reporting agent for PPC, with zero write risk. The whole setup is pipx + three env vars + a config block in your MCP client. The moat is the GAQL prompt library — twelve canonical queries above cover most of what agencies need.

Pair this with a separate REST write workflow and you have the complete programmatic PPC stack. The strategic playbook for pairing reads and writes in 2026 lives in the Google Ads API v23.1 + April 2026 core update playbook.

Frequently Asked Questions