Google Ads MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Ads API integration, enabling AI assistants like Claude, ChatGPT, and Gemini to analyze, manage, and optimize Google Ads campaigns through natural language conversations.

Table of Contents

• Overview

• Features

  • Current Features (v1)

  • Roadmap (v2)

• Quick Start

• Setup & Installation

  • Prerequisites

  • Google Ads API Setup

  • Server Installation

  • AI Integration

• MCP Tool Reference

  • v1 Tools (10 Current Tools)

  • v2 Roadmap (161 Planned Tools)

• Usage Examples

• Configuration

• Architecture

• Troubleshooting

• Advanced Topics

• API Reference

• Contributing

• Security

• License

• Citation

• Support & Resources

Overview

The Google Ads MCP Server transforms how you interact with Google Ads by providing a natural language interface powered by Model Context Protocol. Instead of navigating complex dashboards or writing custom API code, you can analyze campaigns, optimize keywords, and manage budgets through simple conversations with AI assistants.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect with external data sources and tools. This server implements MCP to bridge AI assistants with the Google Ads API.

Key Benefits:

• Natural Language Interface: Ask questions and give commands in plain English

• Multi-Platform Support: Works with Claude Desktop, ChatGPT, Gemini, and other MCP-compatible AI assistants

• Comprehensive Coverage: From basic reporting to advanced campaign management

• Secure: OAuth 2.0 authentication with best-practice credential management

• Extensible: Modular architecture supporting 161 planned tools across 14 functional domains

Features

Current Features (v1)

The current stable release (v1) provides 10 essential tools for Google Ads analysis and management:

Analysis & Reporting

• List all accessible Google Ads accounts

• Campaign performance analysis with filtering and date ranges

• Keyword performance tracking (quality scores, positions, conversions)

• Search terms discovery (actual queries triggering ads)

• Ad group performance metrics

• Google's AI-powered optimization recommendations

Campaign Management

• Update campaign daily budgets

• Pause or enable campaigns

• Execute custom GAQL queries for advanced analysis

Roadmap (v2)

The v2 roadmap expands the server to 161 tools across 14 functional domains, covering approximately 85% of the Google Ads API surface area for campaign management and optimization.

Planned Capabilities:

Total: 161 tools covering end-to-end campaign lifecycle management.

See IMPLEMENTATION_PLAN.md for the complete roadmap.

Quick Start

Get up and running in 5 minutes:

Prerequisites

• Python 3.8 or higher

• Google Ads account with active campaigns

• Google Ads API Developer Token (apply here)

Installation

1. Clone the repository:

   git clone https://github.com/johnoconnor0/google-ads-mcp.git cd google-ads-mcp

2. Install dependencies:

   pip install -r requirements.txt

3. Generate OAuth credentials (see Google Ads API Setup for details):

   python generate_refresh_token.py

4. Configure Claude Desktop (or your preferred AI assistant):

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   { "mcpServers": { "google-ads": { "command": "python", "args": ["/absolute/path/to/google_ads_mcp.py"], "env": {} } } }

5. Restart Claude Desktop and start asking questions about your Google Ads accounts!

First Steps

Once configured, try these commands in Claude Desktop:

See Usage Examples for more.

Setup & Installation

Prerequisites

Required

• Python: Version 3.8 or higher

  python --version # Should output 3.8 or higher

• Google Ads Account: Active account with campaigns

• Google Ads API Access: Developer token (may take 24-48 hours for approval)

• OAuth 2.0 Credentials: Client ID and Client Secret from Google Cloud Console

Optional

• MCC Account: For managing multiple client accounts

• Redis: For distributed caching (optional, defaults to in-memory cache)

Google Ads API Setup

Step 1: Apply for Developer Token

1. Sign in to your Google Ads account

2. Navigate to Tools & Settings → Setup → API Center

3. Apply for a developer token

4. Wait for approval (typically 24-48 hours)

5. Important: Test developer tokens work immediately but have limitations

Resource: Google Ads API Developer Token Guide

Step 2: Create OAuth 2.0 Credentials

1. Go to Google Cloud Console

2. Create a new project (or select existing)

3. Enable the Google Ads API:

   • Navigation → APIs & Services → Library

   • Search for "Google Ads API"

   • Click "Enable"

4. Create OAuth credentials:

   • APIs & Services → Credentials

   • Click Create Credentials → OAuth client ID

   • Choose Desktop app as application type

   • Name your OAuth client (e.g., "Google Ads MCP Server")

   • Click Create

5. Download your credentials or copy:

   • Client ID (ends with .apps.googleusercontent.com)

   • Client Secret

Resource: OAuth 2.0 Setup Guide

Step 3: Generate Refresh Token

Use the provided utility script to generate a refresh token:

What this script does:

1. Opens a browser for Google authorization

2. You grant access to your Google Ads account

3. Generates a refresh token (long-lived credential)

4. Displays the refresh token to copy

Alternative manual method:

Important: Store your refresh token securely! It provides ongoing access to your Google Ads account.

Server Installation

Install Python Dependencies

Option 1: Install from requirements.txt (recommended):

Option 2: Manual installation:

Optional dependencies (for advanced features):

Verify Installation

AI Integration

The Google Ads MCP Server can be integrated with multiple AI platforms:

Claude Desktop Integration

Recommended for: Most users, easiest setup

1. Locate configuration file:

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

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

2. Add MCP server configuration:

   { "mcpServers": { "google-ads": { "command": "python", "args": ["/absolute/path/to/google_ads_mcp.py"], "env": {} } } }

   Replace /absolute/path/to/google_ads_mcp.py with the actual file path.

3. Restart Claude Desktop for changes to take effect

4. Initialize the connection in Claude:

   Initialize my Google Ads connection with these credentials: - Developer Token: YOUR_DEV_TOKEN - Client ID: YOUR_CLIENT_ID.apps.googleusercontent.com - Client Secret: YOUR_CLIENT_SECRET - Refresh Token: YOUR_REFRESH_TOKEN - Login Customer ID: YOUR_MCC_ID (optional, only if using MCC)

Resources:

• Claude Desktop MCP Documentation

• QUICKSTART.md

ChatGPT Integration

Status: Experimental (MCP support via third-party tools)

ChatGPT does not natively support MCP as of December 2025. However, integration is possible via:

Option 1: MCP Bridge (if available)

• Use an MCP-to-OpenAI API bridge

• Configure the bridge to expose Google Ads MCP tools as OpenAI functions

• Access via ChatGPT Plus with plugin support

Option 2: Custom GPT with API Wrapper

• Create a web API wrapper around the MCP server

• Build a Custom GPT with function calling to your API

• Configure authentication and endpoints

Option 3: Use Claude Code or API

• Run the MCP server with Claude Code (CLI)

• Use Claude API to access the MCP tools programmatically

• Integrate results into your ChatGPT workflow

Note: As ChatGPT's MCP support evolves, this section will be updated with native integration instructions.

Gemini Integration

Status: Experimental (MCP support via third-party tools)

Google's Gemini does not natively support MCP as of December 2025. However, integration is possible via:

Option 1: Vertex AI Function Calling

• Deploy the MCP server as a Google Cloud Function or Cloud Run service

• Use Vertex AI's function calling with Gemini

• Map MCP tools to Gemini function definitions

Option 2: LangChain Integration

• Use LangChain to create a bridge between Gemini and MCP tools

• Define MCP tools as LangChain tools

• Create a Gemini agent with MCP tool access

Option 3: Custom Integration

• Build a REST API wrapper around the MCP server

• Use Gemini API with function calling

• Map Google Ads operations to function definitions

Resources:

• Vertex AI Function Calling

• Gemini API Documentation

Other MCP-Compatible Platforms

The server works with any MCP-compatible client. See the MCP Documentation for integration guides.

MCP Tool Reference

v1 Tools (10 Current Tools)

The current stable release provides these tools:

1. google_ads_initialize

Description: Initialize API connection with OAuth credentials.

Parameters:

Example:

Returns: Confirmation message with API version and accessibility check

2. google_ads_list_accounts

Description: List all accessible Google Ads accounts.

Parameters:

Example:

Returns: Account list with customer IDs, names, and descriptive names

3. google_ads_campaign_performance

Description: Get comprehensive campaign metrics with filtering and date ranges.

Parameters:

Example:

Returns: Campaign metrics including impressions, clicks, cost, conversions, CTR, CPC, conversion rate

4. google_ads_keyword_performance

Description: Analyze keyword-level performance with quality scores and positions.

Parameters:

Example:

Returns: Keyword metrics including quality score, average position, impressions, clicks, cost, conversions

5. google_ads_search_terms

Description: Get actual search queries that triggered your ads.

Parameters:

Example:

Returns: Search term, match type, impressions, clicks, cost, conversions, CTR

6. google_ads_ad_group_performance

Description: Analyze ad group-level metrics.

Parameters:

Example:

Returns: Ad group metrics including impressions, clicks, cost, conversions, CTR, CPC

7. google_ads_recommendations

Description: Get Google's AI-powered optimization suggestions.

Parameters:

Example:

Returns: Recommendation type, impact estimate, suggested changes, rationale

8. google_ads_update_campaign_budget

Description: Modify campaign daily budget.

Parameters:

Budget conversion: Multiply your budget by 1,000,000

• $10.00 = 10,000,000 micros

• $50.50 = 50,500,000 micros

• $100.00 = 100,000,000 micros

Example:

Returns: Confirmation with old and new budget values

9. google_ads_update_campaign_status

Description: Pause or enable campaigns.

Parameters:

Example:

Returns: Confirmation with new status

10. google_ads_custom_query

Description: Execute custom GAQL (Google Ads Query Language) queries.

Parameters:

Example:

Resources:

• GAQL Query Builder

• GAQL Documentation

Returns: Query results in requested format

v2 Roadmap (161 Planned Tools)

The v2 implementation expands the server to 161 tools across 14 domains. Below is a summary of planned capabilities.

Campaign Management (23 tools)

Creation & Configuration:

• Create campaigns (all 9 types: Search, Display, Shopping, Video, Performance Max, App, Local, Smart, Demand Gen)

• Configure networks, locations, languages, start/end dates

• Set up budgets (standard, shared, portfolio)

• Configure bidding strategies

Updates & Optimization:

• Modify campaign settings (name, networks, targeting)

• Update location and language targeting

• Manage device bid adjustments

• Configure ad scheduling (dayparting)

• Add campaign-level exclusions

Management:

• Campaign experiments and A/B testing

• Campaign labels and organization

• Campaign deletion and archival

Status: Priority 2 - In active development

Ad & Creative Management (18 tools)

Ad Creation:

• Responsive Search Ads (RSA) - up to 15 headlines, 4 descriptions

• Expanded Text Ads (legacy)

• Responsive Display Ads

• Image ads (Display Network)

• Video ads (YouTube, TrueView)

• Performance Max asset groups

Ad Optimization:

• Ad copy testing and analysis

• Ad strength tracking

• Creative asset management

• Ad preview and testing

Status: Priority 2 - Planned

Keyword Management (15 tools)

Keyword Operations:

• Bulk keyword addition (CSV import)

• Keyword updates (match types, bids, status)

• Keyword deletion

• Negative keyword management

• Negative keyword lists (shared)

Keyword Research & Analysis:

• Keyword forecasting

• Keyword suggestions

• Match type optimization

• Quality score tracking and improvement

Status: Priority 2 - Planned

Bidding & Optimization (12 tools)

Bidding Strategies:

• Portfolio bidding strategies (Target CPA, Target ROAS, Maximize Conversions)

• Bid adjustments (device, location, demographics, audiences, time-of-day)

• Manual bidding configuration

• Smart Bidding setup and monitoring

Optimization:

• Automated rules and triggers

• Bid simulation and forecasting

• Performance optimization suggestions

Status: Priority 2 - Planned

Audience Management (14 tools)

Audience Creation:

• Remarketing lists

• Customer Match audience uploads

• Custom audiences (interests, behaviors)

• Similar audiences (lookalikes)

• In-market and affinity audiences

Audience Targeting:

• Apply audiences to campaigns/ad groups

• Audience bid adjustments

• Exclusion lists

• Audience performance tracking

Status: Priority 3 - Planned

Conversion Tracking (11 tools)

Setup & Configuration:

• Create conversion actions

• Configure conversion tracking tags

• Import offline conversions

• Set up call tracking

Attribution & Analysis:

• Multi-touch attribution models

• Conversion value rules

• Conversion lift studies

• Cross-device conversion tracking

Status: Priority 3 - Planned

Advanced Reporting (25 tools)

Specialized Reports:

• Geographic performance (country, region, city, postal code)

• Demographic reports (age, gender, household income)

• Time-based analysis (hour of day, day of week)

• Device performance breakdown

• Auction insights (competitive analysis)

• Landing page performance

• Call metrics and call tracking

• Video performance (YouTube)

• Shopping performance (product groups)

Report Customization:

• Custom report builder

• Period-over-period comparison

• Trend analysis

• Export to Excel/PDF/CSV

• Scheduled reports

Status: Priority 2-3 - Partially planned

Batch Operations (8 tools)

Bulk Operations:

• Batch campaign creation

• Bulk keyword uploads (CSV)

• Mass ad group creation

• Bulk status changes

• Batch budget updates

Import/Export:

• Google Ads Editor CSV import

• Export campaigns to CSV

• Bulk change history

Status: Priority 3 - Planned

Extensions & Assets (12 tools)

Extension Types:

• Sitelink extensions

• Callout extensions

• Call extensions

• Location extensions

• Price extensions

• Structured snippet extensions

• Promotion extensions

• App extensions

Management:

• Extension performance tracking

• Asset library management

• Extension scheduling

• Extension bid adjustments

Status: Priority 3 - Planned

Shopping & Performance Max (10 tools)

Shopping Campaigns:

• Product feed management

• Product group creation

• Shopping campaign optimization

• Merchant Center integration

Performance Max:

• Asset group creation

• Audience signals

• Performance tracking

• Budget optimization

Status: Priority 3 - Planned

Local & App Campaigns (8 tools)

Local Campaigns:

• Store visits tracking

• Local inventory ads

• Location-based bidding

• Call tracking

App Campaigns:

• App install campaigns

• App engagement campaigns

• Deep link configuration

• In-app event tracking

Status: Priority 3 - Planned

Automation (10 tools)

Automated Rules:

• Create custom rules

• Schedule automated tasks

• Trigger-based actions

• Rule performance tracking

Smart Features:

• Smart Bidding automation

• Automated extensions

• Dynamic ad customization

• AI-powered optimization

Status: Priority 3 - Planned

Insights & Analytics (8 tools)

Forecasting:

• Budget forecasting

• Conversion forecasting

• Seasonal trend analysis

• Growth projections

Competitive Analysis:

• Auction insights

• Competitive benchmarking

• Market share analysis

Change History:

• Account change log

• Performance change attribution

• Rollback capabilities

Status: Priority 3 - Planned

Labels & Organization (7 tools)

Labels:

• Campaign labels

• Ad group labels

• Keyword labels

• Ad labels

Organization:

• Folder structure management

• Resource organization

• Bulk label operations

Status: Priority 3 - Planned

For the complete implementation plan with technical details, see IMPLEMENTATION_PLAN.md.

Usage Examples

Claude Desktop Conversations

Account Overview

Campaign Analysis

Keyword Optimization

Budget Management

Search Terms Discovery

Programmatic Usage

If integrating directly with the MCP server programmatically:

Configuration

Configuration File (config.yaml)

The v2 server supports configuration via YAML files:

Environment Variables

Override configuration with environment variables:

Feature Flags

Enable or disable features:

Caching Options

Memory Cache (default, no setup required):

• Fast, in-process caching

• No external dependencies

• Limited to single process

Redis Cache (recommended for production):

• Distributed caching across processes

• Persistent cache across restarts

• Supports clustering

No Cache:

• Disable caching for testing or debugging

Architecture

Project Structure

Manager Module Pattern

Each domain manager follows this pattern:

MCP Tool Registration System

Tools are registered using FastMCP:

Data Flow

1. AI Assistant sends natural language request

2. MCP Server receives tool call with parameters

3. Manager Module validates input and executes API operation

4. Google Ads API processes the request

5. Response Handler formats the result (Markdown/JSON)

6. MCP Server returns the formatted response

7. AI Assistant presents the result to the user

Troubleshooting

Common Errors

"Client not initialized" Error

Cause: The Google Ads client hasn't been initialized with credentials.

Solution:

"Invalid customer ID" Error

Cause: Customer ID format is incorrect.

Solution: Ensure customer IDs are:

• 10 digits

• Without hyphens

• Example: 1234567890 (correct), 123-456-7890 (wrong)

"Authentication failed" Error

Causes and solutions:

1. Developer token invalid:

   • Verify token in Google Ads API Center

   • Ensure token is approved (not test-only)

2. OAuth credentials incorrect:

   • Regenerate refresh token

   • Verify Client ID and Client Secret

3. Token expired:

   • Refresh tokens can expire after prolonged inactivity

   • Generate a new refresh token

4. Wrong login_customer_id:

   • Only use login_customer_id for MCC accounts

   • Verify the MCC ID is correct

"Insufficient permissions" Error

Causes:

• Your Google account doesn't have access to the Google Ads account

• Developer token has limited access level

• OAuth scope doesn't include Google Ads API

Solution:

1. Verify account access in Google Ads

2. Ensure OAuth scope is https://www.googleapis.com/auth/adwords

3. Check developer token access level

Rate Limiting

Cause: Exceeded Google Ads API rate limits.

Solutions:

• Reduce request frequency

• Use smaller date ranges

• Enable caching (Memory or Redis)

• Implement request throttling

Google Ads API Limits:

• 15,000 operations per day (test accounts)

• Higher limits for production accounts

• Contact Google for increased limits

Debug Logging

Enable debug logging for troubleshooting:

v1 (google_ads_mcp.py):

v2 (config.yaml):

Testing Connections

Test your setup manually:

Getting Help

If you're still stuck:

1. Check existing issues: GitHub Issues

2. Review documentation: Google Ads API Docs

3. Create an issue: Provide error messages, logs, and steps to reproduce

4. Contact support: See Support & Resources

Advanced Topics

Multi-Account (MCC) Management

What is MCC?

MCC (My Client Center) is a Google Ads manager account that lets you manage multiple client accounts from a single interface.

Setup:

1. Create an MCC account at ads.google.com/mcc

2. Link client accounts to your MCC

3. Use MCC customer ID as login_customer_id during initialization

Usage:

Benefits:

• Single authentication for multiple accounts

• Centralized reporting across clients

• Efficient bulk operations

Performance Optimization

Caching Strategies:

1. Memory Cache: Fast, but limited to single process

2. Redis Cache: Distributed, persistent, recommended for production

3. Selective Caching: Cache expensive queries, refresh on mutations

Best Practices:

• Use date range filters to reduce data volume

• Apply limit parameters to control result size

• Enable caching for frequently accessed data

• Use batch operations for bulk changes

Custom GAQL Queries

GAQL (Google Ads Query Language) enables advanced custom queries.

Query Structure:

Example - Find top-performing keywords:

Resources:

• Query Builder

• Query Validator

• GAQL Grammar

Batch Operations

Efficiently make bulk changes using batch operations (v2 feature):

Benefits:

• Reduce API calls (1 batch vs. 100 individual calls)

• Faster execution

• Lower quota usage

Use Cases:

• Bulk keyword uploads

• Mass campaign creation

• Batch budget updates

• Bulk status changes

API Reference

Google Ads API

• Documentation: Google Ads API Docs

• Reference: API Reference

• Field Guide: Field Reference

• Release Notes: What's New

GAQL Resources

• Query Builder: Interactive Query Builder

• Query Validator: Validate Queries

• Query Grammar: GAQL Grammar Reference

MCP Protocol

• Specification: MCP Specification

• Documentation: MCP Docs

• GitHub: MCP GitHub

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Ways to contribute:

• Report bugs or request features via GitHub Issues

• Submit pull requests for bug fixes or new features

• Improve documentation

• Share usage examples and tips

Development workflow:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly

5. Submit a pull request

See CONTRIBUTING.md for detailed instructions.

Security

Security is a top priority. Please see SECURITY.md for:

• Security policy and supported versions

• How to report vulnerabilities

• Security best practices

• Credential management guidelines

Quick security tips:

• Never commit credentials to version control

• Use environment variables for secrets

• Rotate OAuth tokens regularly

• Enable 2FA on Google Ads accounts

• Monitor API access logs

License

This project is licensed under the MIT License. See LICENSE for details.

Citation

If you use this software in your research or project, please cite it:

APA Format:

BibTeX:

See CITATION.cff for machine-readable citation metadata.

Support & Resources

Documentation

• Quick Start: QUICKSTART.md

• Implementation Plan: IMPLEMENTATION_PLAN.md

• Executive Summary: EXECUTIVE_SUMMARY.md

• Claude Instructions: .claude/CLAUDE.md

Google Ads Resources

• Google Ads API: Documentation

• Developer Token: Apply Here

• OAuth Setup: OAuth Guide

• Support: Google Ads API Support

MCP Resources

• MCP Documentation: modelcontextprotocol.io

• Claude Desktop: Claude Desktop Docs

• MCP GitHub: github.com/modelcontextprotocol

Community & Support

• GitHub Issues: Report issues or request features

• Discussions: GitHub Discussions

• Email: open-source@weblifter.com.au

Related Projects

• Claude Desktop: AI assistant with MCP support

• MCP Servers: Awesome MCP Servers

• Google Ads Scripts: Scripts Library

Version: 1.0.0 Last Updated: December 17, 2025 Author: John O'Connor License: MIT

Star this repository if you find it useful!