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

Clone or download this repository

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 .

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:

Client ID & Secret: Create OAuth 2.0 credentials in Google Cloud Console
Developer Token: Apply for one in your Google Ads account (Tools > API Center)
Refresh Token: Generate using the OAuth flow
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

mcp-google-ads