Google Ads MCP Server

A local MCP server for reading and writing the Google Ads API. Full campaign management with a dry-run/confirm safety flow on every write.

Prerequisites

1. Google Ads Manager (MCC) account with a developer token. Check its access level: Google Ads UI -> Tools & Settings -> Setup -> API Center.
   • Test: can only call test accounts. Apply for Basic access to touch live accounts (approval can take a few days).
   • Basic/Standard: ready for live accounts.
2. A Google Cloud project with the Google Ads API enabled and an OAuth2 client of type Desktop app (gives you a client ID and client secret).

Setup

python -m venv .venv
. .venv/Scripts/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Mint a refresh token (one-off browser consent):
python scripts/generate_refresh_token.py --client-id XXX --client-secret YYY

cp .env.example .env          # then fill in every value

If your OAuth consent screen is still in testing mode, add the Google account you sign in with as a test user first (Cloud Console -> APIs & Services -> OAuth consent screen -> Audience), otherwise consent fails with a verification error.

Once .env holds the client ID and secret, python scripts/remint_refresh_token.py re-mints an expired or revoked refresh token and rewrites .env in place, without printing the secret.

Never commit .env; it is gitignored, and it is the only place real credentials should ever live.

.env keys: GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID (your MCC ID, dashes optional, shown top-right in the Google Ads UI when logged into the manager account).

Run the tests

pip install -e ".[dev]"
pytest -v

Register with Claude Code

Use the venv's absolute python path so registration works regardless of which directory Claude Code is launched from (the server also resolves .env from the project root, not the cwd):

# Windows
claude mcp add google-ads -- "<REPO_PATH>\.venv\Scripts\python.exe" -m google_ads_mcp.server

# macOS / Linux
claude mcp add google-ads -- "<REPO_PATH>/.venv/bin/python" -m google_ads_mcp.server

Add --scope user to make the tools available in every project rather than just this one.

Write safety

Every write tool defaults to a preview: it validates the change with the API's validate_only and returns a confirmation_token. To apply, call the same tool again with commit=true and that token. The committed operation is byte-for-byte what was previewed. Nothing spends money until you confirm.

Tools

Read: list_accounts, run_gaql, get_campaigns, get_ad_groups, get_keywords, get_performance.

Write (preview -> confirm): create_campaign_budget, create_campaign, update_budget, update_campaign_status, create_ad_group, update_ad_group_status, create_responsive_search_ad, add_keywords, add_negative_keywords, apply_mutate.