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

Or with environment variables in the config:

Knowledge Configuration

Setting Up App Context

Copy and customize the example file:

Edit app_context.json with your product/service information.

Setting Up User Archetypes

Copy and customize the example file:

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

Running Locally

License

MIT