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

Write / manage

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").

Related MCP server: google-ads-mcp

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

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