🚀 Google Ads MCP Server for Claude Desktop

This project provides a Model Context Protocol (MCP) server that connects Claude Desktop directly to your Google Ads Account, allowing you to analyze and manage your advertising campaigns using natural language.

🏗️ How it works

flowchart LR
    U["You, in plain English"] --> C["Claude Desktop"]
    C <-->|MCP stdio| S["google-ads-mcp<br/>server.py"]
    S -->|google-ads.yaml found| G["Google Ads API<br/>7 live tools"]
    S -->|no credentials| M["Mock mode<br/>simulated campaigns, zero risk"]

A typical request, end to end:

sequenceDiagram
    actor You
    participant Claude as Claude Desktop
    participant MCP as MCP Server
    participant Ads as Google Ads API or Mock
    You->>Claude: Raise the bid on summer t-shirts to $2
    Claude->>MCP: update_keyword_bid ad_group 2001, keyword 3001, 2.0
    MCP->>Ads: mutate CPC bid
    Ads-->>MCP: success
    MCP-->>Claude: confirmation with new bid
    Claude-->>You: Done — bid is now $2.00

Related MCP server: Paid Media MCP

🛠️ Features

Exposes seven powerful tools directly to Claude Desktop:

1. Campaign Management:

   • get_campaigns: Lists all active/paused campaigns, budget allocation, and performance metrics (Impressions, Clicks, Conversions, Spend).

   • update_campaign_status: Toggles campaign status (ENABLED or PAUSED) by Campaign ID.

   • set_campaign_budget: Modifies the daily budget of any campaign (in USD).

2. Ad Group Management:

   • get_ad_groups: Lists all ad groups with their names, IDs, status, and target campaign.

3. Keyword Management & PPC Bidding:

   • get_keywords: Pulls keywords with performance metrics (clicks, impressions, conversions, current bids). Optionally filter by Ad Group ID.

   • ** add_keyword**: Adds a new keyword (Broad/Phrase/Exact match) under a specific ad group with a manual CPC bid limit.

   • update_keyword_bid: Modifies the Max CPC bid limit (in USD) for a specific keyword in an ad group.

📂 Project Structure

• server.py: The MCP server. Runs in Mock (Simulation) Mode if no credentials are found, allowing you to test it instantly without API access.

• auth_helper.py: Interactive script to authenticate and generate OAuth refresh_token.

• requirements.txt: Python package dependencies.

⚡ Quick Start & Setup (Windows Auto Setup)

If you are on Windows, we have provided an automated setup script to configure everything for you:

1. Double-click the setup.bat file in this project folder.

2. The script will automatically install dependencies, guide you through the OAuth login browser flow, and open the Claude Desktop config folder.

3. Paste the configuration JSON block (shown below) into your claude_desktop_config.json and restart Claude Desktop.

🛠️ Manual Configuration (Alternative)

If you prefer to configure the environment manually:

1. Create a Python Virtual Environment

Open your terminal (PowerShell or Bash) and run:

# Navigate to this folder
cd /path/to/this/folder

# Create virtual environment
python -m venv .venv

# Activate it (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Activate it (macOS/Linux)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure Claude Desktop

Open your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration (make sure to replace the paths with absolute paths to your Python executable and project folder):

{
  "mcpServers": {
    "google-ads-manager": {
      "command": "C:\\path\\to\\project\\.venv\\Scripts\\python.exe",
      "args": [
        "-u",
        "C:\\path\\to\\project\\server.py"
      ],
      "env": {
        "MOCK_MODE": "true"
      }
    }
  }
}

⚠️ Windows Warning: Use double backslashes (\\) in paths. Make sure the executable points directly to your .venv script to avoid environment mismatches.

3. Restart Claude Desktop

Restart your Claude Desktop application. You should see a small hammer icon 🔨 in the input box, showing that the Google Ads Manager server tools are loaded!

Try typing:

• "Show me my google ads campaigns"

• "Show me keywords in ad group 2001"

• "Add exact keyword 'buy shoes' to ad group 2001 with cpc bid of 1.50"

• "Pause campaign 1002"

• "Increase daily budget of campaign 1001 to $65"

💼 Going Live (Real Google Ads Integration)

To connect the server to your real live Google Ads account, follow these steps:

1. Place your GCP client secrets file

1. Go to your Google Cloud Console -> Credentials.

2. Download your OAuth 2.0 Client credentials JSON file (Desktop Application type).

3. Put this .json file in this project folder.

2. Run the Auth Helper script

With your virtual environment active, run:

python auth_helper.py

• This will open your browser and ask you to log in to your Google Account.

• After clicking Allow, return to your terminal and enter your Developer Token and Client Customer ID.

• This script will automatically generate a secure google-ads.yaml configuration file.

3. Update Claude Config for Live Mode

Edit your claude_desktop_config.json and change "MOCK_MODE": "true" to "false" (or delete the "env" section).

Restart Claude Desktop, and you are live!

⚠️ Troubleshooting (常见问题排查)

Q1: Browser shows "This app isn't verified" (此应用未经 Google 验证)

• Reason: Since this is a custom local tool, it has not gone through Google's public verification process. This is completely normal and safe.

• Solution: Click "Advanced" (高级) in the bottom left, then click "Go to your-project-name (unsafe)" (继续前往) to complete the authorization.

Q2: Error 403: access_denied / App has not completed verification

• Reason: Your GCP project is in "Testing" mode, and the Google account you are using to log in is different from the account that owns the GCP project.

• Solution:

  1. Make sure you select the same Google account that created the GCP credentials during the OAuth flow.

  2. Alternatively, go to your GCP Console -> Google Auth Platform -> Audience (测试受众) -> Click "+ ADD USERS" under Test Users, and add your login email address.

Built by Bohea Still — independent developer taking on automation, AI-pipeline and integration projects. Case study →