Google Ads MCP

MCP server for Google Ads keyword planning, Search campaign management, reporting, and basic optimization workflows.

This server runs over stdio and is intended to be launched by an MCP client such as Claude Cowork or any other client that supports local stdio MCP servers.

What It Does

• Keyword discovery and historical metrics
• Forecasting for keyword sets
• Search campaign creation and updates
• Ad group and keyword management
• Negative keyword management at the campaign, ad group, shared-list, and account levels
• Responsive search ad creation and replacement-style updates
• Search term and performance reporting

Mutation tools return structured results. Reporting tools return markdown tables.

Requirements

• Python >=3.11
• uv
• A Google Ads API-enabled Google Cloud project
• Google Ads API credentials
• A Google Ads customer ID
• Optional MCC login customer ID

Configuration

Copy .env.example to .env and fill in:

GOOGLE_ADS_DEVELOPER_TOKEN=
GOOGLE_ADS_CLIENT_ID=
GOOGLE_ADS_CLIENT_SECRET=
# Optional at startup if you will use the `authorize` MCP tool
GOOGLE_ADS_REFRESH_TOKEN=
GOOGLE_ADS_CUSTOMER_ID=
# GOOGLE_ADS_LOGIN_CUSTOMER_ID=

How To Obtain The Tokens

You need four values to boot the server in OAuth mode, and a fifth once you complete authorization:

• GOOGLE_ADS_DEVELOPER_TOKEN
• GOOGLE_ADS_CLIENT_ID
• GOOGLE_ADS_CLIENT_SECRET
• GOOGLE_ADS_CUSTOMER_ID

After first-time authorization, you will also have:

• GOOGLE_ADS_REFRESH_TOKEN

Optional:

• GOOGLE_ADS_LOGIN_CUSTOMER_ID for MCC / manager-account access

1. Get A Google Ads Developer Token

In your Google Ads account:

1. Open Tools and settings.
2. Open API Center.
3. Copy your developer token.

Use that value for GOOGLE_ADS_DEVELOPER_TOKEN.

2. Create An OAuth Client ID And Secret

In Google Cloud:

1. Create or select a Google Cloud project.
2. Enable the Google Ads API for that project.
3. Open APIs & Services -> Credentials.
4. Create an OAuth client ID.
5. For local use, a Desktop app client is usually the simplest option.
6. Copy the client ID and client secret.

Use those values for:

• GOOGLE_ADS_CLIENT_ID
• GOOGLE_ADS_CLIENT_SECRET

3. Complete OAuth Authorization

For OAuth, the server can now start with just:

• GOOGLE_ADS_CLIENT_ID
• GOOGLE_ADS_CLIENT_SECRET
• GOOGLE_ADS_DEVELOPER_TOKEN
• GOOGLE_ADS_CUSTOMER_ID

Once the MCP server is running, call:

authorize

That tool will:

1. open a Google authorization URL in your browser
2. complete the local callback flow
3. save GOOGLE_ADS_REFRESH_TOKEN into your .env
4. make future MCP runs use the saved token automatically

4. Find The Customer IDs

• GOOGLE_ADS_CUSTOMER_ID: the Google Ads account the server should operate on
• GOOGLE_ADS_LOGIN_CUSTOMER_ID: the manager account to authenticate through, if you are using an MCC

You can copy these from the Google Ads UI. The server accepts IDs with or without dashes and normalizes them internally.

Example .env

GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_CLIENT_ID=your-oauth-client-id
GOOGLE_ADS_CLIENT_SECRET=your-oauth-client-secret
# Optional until you run the `authorize` tool
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
GOOGLE_ADS_CUSTOMER_ID=1234567890
GOOGLE_ADS_LOGIN_CUSTOMER_ID=0987654321

Install dependencies:

uv sync

Run locally:

uv run google-ads-mcp

If you are using OAuth and have not authorized yet, start the MCP server and call authorize.

Claude Cowork / MCP Client Setup

If your MCP client supports stdio servers with environment variables, configure this repo with a command like:

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["run", "google-ads-mcp"],
      "cwd": "/absolute/path/to/google-ads",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "0987654321"
      }
    }
  }
}

If your client loads environment variables from the repo automatically, you can omit the env block and rely on the local .env file instead.

Notes:

• cwd should point at this repository root.
• GOOGLE_ADS_CUSTOMER_ID and GOOGLE_ADS_LOGIN_CUSTOMER_ID may include or omit dashes; the server normalizes them.
• For manager-account access, set GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Files

.
├── .env.example
├── pyproject.toml
├── README.md
├── src/google_ads_mcp/
│   ├── client.py
│   ├── config.py
│   ├── formatters.py
│   ├── models.py
│   └── server.py
├── tests/
│   ├── test_client.py
│   └── test_server.py
└── uv.lock

File summary:

• src/google_ads_mcp/server.py: FastMCP server and tool registration
• src/google_ads_mcp/client.py: Google Ads API wrapper and mutation/report logic
• src/google_ads_mcp/models.py: typed request and structured response models
• src/google_ads_mcp/formatters.py: markdown formatting for report tools
• src/google_ads_mcp/config.py: environment loading and validation
• tests/test_client.py: request-construction and client behavior tests
• tests/test_config.py: environment-loading and OAuth bootstrap tests
• tests/test_server.py: MCP tool registration and output-shape tests

Tools

Authentication

• check_auth_status
• authorize
• reauthorize

Keyword Planning

• generate_keyword_ideas
• get_keyword_historical_metrics
• generate_keyword_forecast

Campaign Structure

• create_search_campaign
• update_search_campaign
• set_campaign_geo_targets
• set_campaign_ad_schedule
• set_campaign_device_bid_adjustments
• list_negative_keywords_in_campaign
• add_negative_keywords_to_campaign
• update_negative_keywords_in_campaign
• remove_negative_keywords_from_campaign
• create_ad_group
• update_ad_group
• add_keywords_to_ad_group
• update_keywords
• remove_keywords
• list_negative_keywords_in_ad_group
• add_negative_keywords_to_ad_group
• update_negative_keywords_in_ad_group
• remove_negative_keywords_from_ad_group

Shared Negative Lists

• create_shared_negative_keyword_list
• update_shared_negative_keyword_list
• list_shared_negative_keyword_lists
• list_keywords_in_shared_negative_list
• add_keywords_to_shared_negative_list
• remove_keywords_from_shared_negative_list
• apply_shared_negative_keyword_list_to_campaigns
• remove_shared_negative_keyword_list_from_campaigns
• get_account_negative_keyword_list
• apply_shared_negative_keyword_list_to_account
• remove_shared_negative_keyword_list_from_account

Ads

• create_responsive_search_ad
• update_responsive_search_ad

Campaign Assets

• create_campaign_sitelink_asset
• create_campaign_callout_asset
• create_campaign_structured_snippet_asset
• create_campaign_call_asset

Conversion Tracking

• create_conversion_action
• update_conversion_action

Reporting

• get_search_term_report
• get_performance_report

Safety Notes

• This server performs live Google Ads mutations.
• New campaigns, ad groups, keywords, and RSAs default to PAUSED unless you explicitly request ENABLED.
• Campaign assets and conversion actions are durable Google Ads resources. Treat them as production-impacting operations.
• RSA creative updates are implemented as replace-and-remove because Google Ads treats most RSA creative fields as immutable.

Testing

Run tests with:

uv run python -m unittest discover -s tests -v