# 🚀 Google Ads MCP Server for Claude Desktop

[![CI](https://github.com/boheastill/google-ads-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/boheastill/google-ads-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```mermaid
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:

```mermaid
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
```

---

## 🛠️ 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:
```bash
# 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):

```json
{
  "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:
```bash
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](https://boheastill.com/?r=gh-gads) — independent developer taking on automation, AI-pipeline and integration projects. [Case study →](https://boheastill.com/cases/google-ads-mcp?r=gh-gads)*