google-ads-mcp-server

A Model Context Protocol (MCP) server for Google Ads with both read and write access. Connect it to Claude (or any MCP client) and pull reports with GAQL, then actually manage the account — create and adjust budgets, campaigns, ad groups, bids, and keywords — in natural language, using your own Google Ads credentials.

Google's own official Google Ads MCP server is read-only. This one adds the write side, and does it carefully.

🛑 Writes spend real money — how the safety guard works

Google Ads changes cost money, so every write tool is a dry run by default. When you call a write tool without confirm=True, the change is sent to the Google Ads API with its validate_only flag: the API checks that the change is valid but does not apply it, and the tool tells you it was validated only. The change is applied only when you call the same tool again with confirm=True.

That means the safe loop is always: call once to validate → review → call again with confirm=True to apply. New campaigns are also created PAUSED by default so nothing starts serving unexpectedly.

Related MCP server: google-ads-mcp

Features

Read

• ads_whoami and list_accessible_customers — verify credentials and see which accounts you can reach

• search — run any GAQL query (the general-purpose read tool)

• Convenience listers: campaigns, ad groups, ads, budgets, keywords

• campaign_performance — impressions/clicks/cost/conversions by campaign over a date range

Write (dry run unless confirm=True)

• Create and update campaign budgets

• Create campaigns (paused Search + Manual CPC by default) and set campaign status (enable/pause/remove)

• Create ad groups, set ad group status, and change ad group bids

• Add keywords and set keyword status

Requirements

• Python 3.10+

• A Google Ads developer token. Test tokens only work against test accounts; to read or write real accounts you need Basic access, which is a short application in the API Center of a manager (MCC) account.

• Credentials — either OAuth2 (client id, client secret, refresh token) or a service account with domain-wide delegation (Google Workspace).

• Your manager account id as the login customer id.

Google setup (one time)

1. In a Google Ads manager (MCC) account, open API Center and apply for a developer token with Basic access.

2. In the Google Cloud Console, create a project and enable the Google Ads API.

3. Create OAuth 2.0 credentials (Desktop app) and generate a refresh token for an account that can access your Google Ads accounts. (Google's OAuth desktop guide walks through this; the google-ads library ships a helper script for the refresh token.)

4. Note your login customer id (the MCC id, digits only).

Alternatively, use a service account with domain-wide delegation on a Workspace and point the config at its key — see the google-ads configuration docs.

Install

Using uv (recommended):

git clone https://github.com/burhan29ee/google-ads-mcp-server.git
cd google-ads-mcp-server
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .

Or with pip:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Configure your MCP client

The server reads the standard GOOGLE_ADS_* environment variables (or a google-ads.yaml via GOOGLE_ADS_CONFIGURATION_FILE_PATH). For Claude Desktop, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "/absolute/path/to/google-ads-mcp-server/.venv/bin/python",
      "args": ["-m", "google_ads_mcp_server.server"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_CLIENT_ID": "your-oauth-client-id.apps.googleusercontent.com",
        "GOOGLE_ADS_CLIENT_SECRET": "your-oauth-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-oauth-refresh-token"
      }
    }
  }
}

Restart the client and start with "run ads_whoami" to confirm access. Then try "show my top campaigns by spend over the last 30 days" or "pause campaign 12345" (which will dry-run first).

Tool reference

Amounts and bids are in micros (1,000,000 micros = 1 unit of the account currency; e.g. a $5.00 daily budget is 5000000).

Development

pip install -e ".[dev]"
ruff check .
pytest -q

See CONTRIBUTING.md for the full workflow.

Security

Credentials here can change spend — treat them like production secrets. Never commit them (the .gitignore blocks key files, .env, and google-ads.yaml), grant least access, prefer a test account while evaluating, and keep the dry-run guard: review the validate_only result before re-running with confirm=True. See SECURITY.md.

Notes

• The mcp dependency is pinned to >=1.2,<2. The 2.0 SDK reorganized its API and removed mcp.server.fastmcp, which this server uses.

• This is an independent open-source project and is not affiliated with or endorsed by Google. It is separate from Google's official read-only google-ads-mcp.

License

MIT