google-ads-mcp

Google Ads MCP Server

MCP server for Google Ads campaign reporting and management via Claude.

Setup

1. Google Cloud Console

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Google Ads API
4. Go to APIs & Services > Credentials
5. Create an OAuth 2.0 Client ID (type: Desktop app)
6. Note your Client ID and Client Secret

2. Developer Token

1. Sign in to your Google Ads account
2. Go to Tools & Settings > API Center (ads.google.com/aw/apicenter)
3. Apply for a developer token (test accounts get one immediately)
4. Note your Developer Token

3. OAuth Refresh Token

# Set your credentials first
export GOOGLE_ADS_CLIENT_ID=your_client_id
export GOOGLE_ADS_CLIENT_SECRET=your_client_secret

# Run the auth setup
npm run auth

This opens a browser for Google sign-in. After authorizing, you'll get a refresh token.

4. Find Your Customer ID

Your Google Ads Customer ID is the 10-digit number shown in the top-right of the Google Ads UI (e.g., 123-456-7890). Enter it without dashes: 1234567890.

5. Configure in Claude Code

Add to your Claude Code settings (~/.claude/settings.local.json or project-level):

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/path/to/google-ads-mcp/dist/index.js"],
      "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"
      }
    }
  }
}

Manager Account (MCC)

If your refresh token is from a Manager Account that manages the target account, add:

"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_manager_account_id"

Tools (14 total)

Reporting (8 tools)

• gads_query - Execute custom GAQL queries
• gads_campaign_performance - Campaign metrics with date range and status filters
• gads_adgroup_performance - Ad group metrics, filterable by campaign
• gads_keyword_performance - Keyword metrics with quality score
• gads_ad_performance - Ad-level metrics with headlines/descriptions
• gads_search_terms - Search terms that triggered ads
• gads_account_summary - High-level account overview
• gads_budget_report - Budget utilization per campaign

Accounts (1 tool)

• gads_list_accounts - List accessible customer accounts

Management (5 tools)

• gads_list_campaigns - List campaigns with configuration
• gads_set_campaign_status - Enable or pause a campaign
• gads_update_campaign_budget - Update daily budget
• gads_set_adgroup_status - Enable or pause an ad group
• gads_set_keyword_status - Enable, pause, or remove a keyword

Build

npm install
npm run build

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_ADS_DEVELOPER_TOKEN | Yes | From Google Ads API Center | | GOOGLE_ADS_CLIENT_ID | Yes | OAuth2 client ID | | GOOGLE_ADS_CLIENT_SECRET | Yes | OAuth2 client secret | | GOOGLE_ADS_REFRESH_TOKEN | Yes | From npm run auth | | GOOGLE_ADS_CUSTOMER_ID | Yes | 10-digit account ID (no dashes) | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | No | Required if using Manager Account |