Google Ads MCP Server

An MCP (Model Context Protocol) server for managing Google Ads campaigns through Claude Desktop, featuring a three-layer architecture for intelligent campaign management.

Architecture

This MCP server uses a three-layer architecture:

1. Knowledge Layer (Resources)

Provides context and insights to Claude:

• App Context: Product information, value propositions, target audiences

• User Archetypes: Persona definitions, pain points, motivations

• Keyword Research: Keyword lists, search volumes, competition data

2. Action Layer (Tools)

Executes operations in Google Ads:

• Campaigns: List, create, update, pause campaigns

• Ad Groups: Manage ad groups within campaigns

• Ads: Create and manage responsive search ads

• Keywords: Add, update bids, pause keywords

• Reports: Generate performance reports

3. Memory Layer (Persistence)

Tracks history and learnings:

• Change Log: All modifications made to the account

• Report History: Past performance reports for comparison

• Decisions: Why certain choices were made

• Learnings: What worked, what didn't, insights gained

Setup

Prerequisites

• Python 3.10+

• Google Ads API credentials

• Claude Desktop

Installation

1. Clone or download this repository

2. Create a virtual environment and install dependencies:

   # Using uv (recommended)
   uv venv
   uv sync
   
   # Or using pip
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .

3. Configure your Google Ads credentials:

   cp .env.example .env
   # Edit .env with your credentials

Google Ads API Credentials

You'll need the following credentials from the Google Ads API:

1. Client ID & Secret: Create OAuth 2.0 credentials in Google Cloud Console

2. Developer Token: Apply for one in your Google Ads account (Tools > API Center)

3. Refresh Token: Generate using the OAuth flow

4. Customer ID: Your Google Ads account ID (without dashes)

See the Google Ads API documentation for detailed setup instructions.

Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/dev/mcps/google-ads",
        "run",
        "google-ads-mcp"
      ]
    }
  }
}

Or with environment variables in the config:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["C:/dev/mcps/google-ads/src/server.py"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_ADS_CUSTOMER_ID": "your_customer_id"
      }
    }
  }
}

Knowledge Configuration

Setting Up App Context

Copy and customize the example file:

cp data/knowledge/app_context.example.json data/knowledge/app_context.json

Edit app_context.json with your product/service information.

Setting Up User Archetypes

Copy and customize the example file:

cp data/knowledge/archetypes.example.json data/knowledge/archetypes.json

Edit archetypes.json with your target audience personas.

Available Tools

Campaign Management

• list_campaigns - List all campaigns

• get_campaign - Get campaign details

• create_campaign - Create a new campaign

• update_campaign - Update campaign settings

• set_campaign_status - Pause/enable campaigns

Ad Group Management

• list_ad_groups - List ad groups

• create_ad_group - Create an ad group

• update_ad_group - Update ad group settings

Ad Management

• list_ads - List ads

• create_responsive_search_ad - Create an RSA

• update_ad_status - Change ad status

Keyword Management

• list_keywords - List keywords

• add_keywords - Add new keywords

• update_keyword_bid - Adjust bids

• pause_keyword - Pause keywords

Reporting

• get_campaign_report - Campaign performance

• get_keyword_report - Keyword performance

• get_search_terms_report - Search query data

• get_performance_metrics - Account summary

Memory Tools

• get_change_history - View change log

• save_report_snapshot - Store reports

• get_historical_reports - Compare over time

• log_decision - Record decisions

• get_decision_history - View decisions

• record_learning - Store insights

• get_insights - Retrieve learnings

Development

Project Structure

google-ads/
├── src/
│   ├── server.py              # Main MCP server
│   ├── config.py              # Configuration
│   ├── google_ads_client.py   # API wrapper
│   ├── knowledge/             # Knowledge layer
│   ├── actions/               # Action layer (tools)
│   └── memory/                # Memory layer
├── data/
│   └── knowledge/             # Knowledge files
├── pyproject.toml
└── README.md

Running Locally

# Run the server directly
python src/server.py

# Or using the entry point
google-ads-mcp

License

MIT