Google Ads MCP Server

An MCP server that connects an MCP client (Claude Desktop, etc.) to the Google Ads API v23. You log into your Google account once; after that every tool operates on the ad accounts that login can access — read reporting and full campaign management.

Built with the official google-ads Python client and FastMCP.

---

What it can do

Read

Tool	Purpose
google_ads_list_accessible_customers	List the account IDs your login can access
google_ads_search	Run any GAQL query (the flexible workhorse)
google_ads_list_campaigns	Campaigns with status, channel type, budget
google_ads_list_ad_groups	Ad groups, optionally filtered to a campaign
google_ads_get_performance	Impressions, clicks, cost, conversions by account/campaign/ad group

Write / manage

Tool	Purpose
google_ads_create_campaign_budget	Create a daily budget
google_ads_create_campaign	Create a campaign (PAUSED by default)
google_ads_update_campaign_status	Enable / pause / remove a campaign
google_ads_update_campaign_budget	Change a budget's daily amount
google_ads_create_ad_group	Create an ad group under a campaign

New campaigns are created PAUSED so nothing spends until you explicitly enable them. Money values are entered in normal currency units (the server converts to/from API "micros").

---

Important: login alone is not enough

The Google Ads API can't authorize from a Google login by itself. Three things are required, and the steps below get you all three:

1. A developer token — from your Google Ads manager account (one-time, may need Google approval).
2. An OAuth client (client ID + secret) — from Google Cloud Console.
3. A refresh token — produced when you log in (get_refresh_token.py).

Once these sit in .env, the server works.

---

Setup

0. Requirements

• Python 3.9+
• A Google Ads account, and access to a manager (MCC) account to get a developer token.

1. Install dependencies

cd google-ads-mcp
python -m pip install -r requirements.txt

2. Get a developer token

Google Ads UI → Tools → API Center (must be a manager account). Copy the developer token. A brand-new token starts in test mode (works only against test accounts); apply for Basic access to use it on real accounts.

3. Create an OAuth client (Desktop app)

In Google Cloud Console:

1. Create/select a project.
2. APIs & Services → Library → enable Google Ads API.
3. APIs & Services → Credentials → Create credentials → OAuth client ID.
4. Application type: Desktop app. Copy the client ID and client secret. (Add your Google account as a Test user on the OAuth consent screen if the app is in "Testing".)

4. Log in to get your refresh token

python get_refresh_token.py

A browser opens — choose the Google account that has access to your Google Ads account and approve. The script prints the refresh token and writes the client ID/secret + refresh token into .env.

5. Fill in .env

Copy the template and complete the remaining values:

cp .env.example .env   # Windows: copy .env.example .env

At minimum set:

GOOGLE_ADS_DEVELOPER_TOKEN=...      # from step 2
GOOGLE_ADS_CLIENT_ID=...            # from step 3 (also written by step 4)
GOOGLE_ADS_CLIENT_SECRET=...        # from step 3 (also written by step 4)
GOOGLE_ADS_REFRESH_TOKEN=...        # from step 4
# Manager accounts only:
GOOGLE_ADS_LOGIN_CUSTOMER_ID=...    # your MCC id, 10 digits
# Optional convenience:
GOOGLE_ADS_DEFAULT_CUSTOMER_ID=...  # the account most tools act on

6. Smoke-test

python -c "import server; print('server imports OK')"

Then verify credentials end-to-end (lists your accounts):

python -c "import asyncio, server; from server import ListCustomersInput; \
print(asyncio.run(server.google_ads_list_accessible_customers(ListCustomersInput())))"

7. Connect it to Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and add — using the absolute path to server.py:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/google-ads-mcp/server.py"]
    }
  }
}

The server reads .env from its own folder, so no secrets need to go in this config. Restart Claude Desktop; the Google Ads tools will appear.

---

Example prompts

• "List my Google Ads accounts."
• "Show campaign performance for the last 30 days."
• "Run GAQL: SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.clicks DESC."
• "Create a $20/day budget called 'Summer', then a paused Search campaign 'Summer Sale' using it."
• "Pause campaign 1234567890."

---

Manager (MCC) accounts

If your login is a manager account operating client accounts, set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager id, and pass the client account id as customer_id (or set GOOGLE_ADS_DEFAULT_CUSTOMER_ID).

---

Troubleshooting

Symptom	Fix
Missing Google Ads credentials: ...	Fill the named vars in .env.
invalid_grant / RefreshError	Refresh token expired/revoked — re-run get_refresh_token.py.
DEVELOPER_TOKEN_NOT_APPROVED / token in test mode	Apply for Basic access, or use a test account.
USER_PERMISSION_DENIED	Login lacks access to that account, or login_customer_id is wrong/missing for MCC.
CUSTOMER_NOT_FOUND	Check the 10-digit customer_id (dashes are fine, they're stripped).
No refresh token returned	Revoke prior access at myaccount.google.com/permissions, re-run the login.

---

Security

• .env holds secrets and is git-ignored — never commit it.
• The developer token, OAuth secret, and refresh token together grant access to your ad accounts; treat them like passwords.
• All write tools are annotated (destructiveHint on remove/pause) so clients can warn before acting.

Project layout

google-ads-mcp/
├── server.py             # FastMCP server + all 10 tools
├── ads_client.py         # credentials, client factory, error handling, helpers
├── get_refresh_token.py  # one-time OAuth login -> refresh token
├── requirements.txt
├── .env.example          # copy to .env and fill in
├── .gitignore
└── README.md