Google Ads

What is google-ads-mcp-server?

The google-ads-mcp-server is a FastMCP-powered Model Context Protocol server designed to integrate the Google Ads API with AI assistants like Claude Desktop. It provides programmatic access to Google Ads data and management features, enabling users to analyze performance data and manage campaigns through natural language conversations.

How to use google-ads-mcp-server?

To use google-ads-mcp-server, you need to follow a few steps:

1. Google Cloud Platform Setup: Create a Google Cloud Project, enable the Google Ads API, and create OAuth 2.0 credentials (Desktop application type). Download the client_secret_[long-string].json file.
2. Google Ads API Setup: Obtain a Developer Token from your Google Ads account.
3. Installation & Setup: Clone the repository, create a virtual environment, install dependencies (pip install -r requirements.txt), and configure the .env file with your GOOGLE_ADS_DEVELOPER_TOKEN and GOOGLE_ADS_OAUTH_CONFIG_PATH.
4. Claude Desktop Integration: Locate your Claude Desktop configuration file (claude_desktop_config.json) and add the google-ads MCP server configuration, specifying the absolute paths to your Python executable and server.py.
5. First-Time Authentication: Restart Claude Desktop and trigger an OAuth flow by trying any Google Ads command. Complete the authentication in your browser, granting permissions to your Google account. A google_ads_token.json file will be created locally.

Once set up, you can interact with the Google Ads API using natural language queries within Claude Desktop.

Key Features of google-ads-mcp-server

• Automatic OAuth 2.0: One-time browser authentication with automatic token refresh.
• Smart Token Management: Handles expired tokens automatically.
• GAQL Query Execution: Run any Google Ads Query Language (GAQL) queries.
• Account Management: List and manage Google Ads accounts.
• Keyword Research: Generate keyword ideas with search volume data.
• FastMCP Framework: Built on the modern MCP standard for seamless integration.
• Claude Desktop Ready: Direct integration with Claude Desktop.
• Secure Local Storage: Tokens are stored locally and never exposed.
• Available Tools: Includes list_accounts, run_gaql, and run_keyword_planner for various operations.

Use Cases of google-ads-mcp-server

• Basic Account Operations: List all Google Ads accounts and view account details.
• Campaign Analysis: Analyze campaign performance (e.g., clicks, cost, conversions) for specific date ranges or identify campaigns with high cost per conversion.
• Keyword Research: Generate keyword ideas, find keyword opportunities with search volume data, and research keywords for specific URLs.
• Custom GAQL Queries: Execute custom GAQL queries to retrieve specific data points, such as campaign performance with revenue, keyword performance analysis, or device performance breakdown.
• Integration with AI Assistants: Connect Google Ads data directly to AI assistants for natural language-based data analysis and management.

FAQ from google-ads-mcp-server

Q: What are the common authentication issues and how to resolve them?

A: If "No tokens found" appears, it's normal for first-time setup; complete browser authentication. If "Token refresh failed," delete google_ads_token.json and re-authenticate. For browser errors or no response during OAuth flow, check credentials file path and internet connection. If "Access denied," ensure your Google account has Google Ads access.

Q: How to troubleshoot configuration issues?

A: If "Environment variable not set," check your .env file and Claude config. For "FileNotFoundError," verify absolute paths. If "ModuleNotFoundError," run pip install -r requirements.txt. For "Command not found" related to Python, use the absolute path to the Python executable.

Q: What if Claude Desktop is not connecting or showing errors?

A: Restart Claude Desktop and check your configuration file syntax. If permission errors occur, check file permissions and paths.

Q: How to handle API issues like invalid customer ID or quota exceeded?

A: For "Customer not found," use the 10-digit format without dashes (e.g., 1234567890). If "Quota exceeded," wait for the quota to reset or request an increase. For "Authentication failed" due to an invalid developer token, verify the token in Google Ads API Center. For GAQL syntax errors, check your query syntax and field names.

Q: How can I enable debug mode?

A: Add import logging and logging.basicConfig(level=logging.DEBUG) to server.py for detailed logging.

Q: What are the Google Ads API quotas?

A: Basic access allows 15,000 operations per day, and standard access allows 40,000 operations per day. The request rate is 1,600 requests per minute per developer token.

Q: What are the best practices for API usage?

A: Cache results, use date ranges to limit data, batch requests when supported, monitor usage in Google Cloud Console, and implement retry logic for rate limit errors.

Q: Can I deploy the server for web or remote access?

A: Yes, you can start the server in HTTP mode using python3 server.py --http and configure Claude Desktop with the appropriate URL (e.g., http://127.0.0.1:8000/mcp).

Q: How can I customize the token storage location?

A: Modify the get_token_path() function in oauth/google_auth.py to return your desired custom path.

Q: How do I configure for a manager account (MCC)?

A: Add GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890 to your .env file.

Google Ads MCP Server 🚀

A FastMCP-powered Model Context Protocol server for Google Ads API integration with automatic OAuth 2.0 authentication

Connect Google Ads API directly to Claude Desktop and other MCP clients with seamless OAuth 2.0 authentication, automatic token refresh, GAQL querying, and keyword research capabilities.

Your browser does not support the video tag.

Easy One-Click Setup

For a simpler setup experience, we offer ready-to-use installers:

👉 Download installer - https://gomarble.ai/mcp

Join our community for help and updates

👉 Slack Community - AI in Ads

Try Facebook ads mcp server also

👉 Facebook Ads MCP - Facebook Ads MCP

✨ Features

• 🔐 Automatic OAuth 2.0 - One-time browser authentication with auto-refresh
• 🔄 Smart Token Management - Handles expired tokens automatically
• 📊 GAQL Query Execution - Run any Google Ads Query Language queries
• 🏢 Account Management - List and manage Google Ads accounts
• 🔍 Keyword Research - Generate keyword ideas with search volume data
• 🚀 FastMCP Framework - Built on the modern MCP standard
• 🖥️ Claude Desktop Ready - Direct integration with Claude Desktop
• 🛡️ Secure Local Storage - Tokens stored locally, never exposed

📋 Available Tools

Tool	Description	Parameters	Example Usage
list_accounts	List all accessible Google Ads accounts	None	"List all my Google Ads accounts"
run_gaql	Execute GAQL queries with custom formatting	customer_id, query, manager_id (optional)	"Show me campaign performance for account 1234567890"
run_keyword_planner	Generate keyword ideas with metrics	customer_id, keywords, manager_id, page_url, date range options	"Generate keyword ideas for 'digital marketing'"

Note: All tools automatically handle authentication - no token parameters required!

🚀 Quick Start

Prerequisites

Before setting up the MCP server, you'll need:

• Python 3.10+ installed
• A Google Cloud Platform account
• A Google Ads account with API access

🔧 Step 1: Google Cloud Platform Setup

1.1 Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project:
   • Click "Select a project" → "New Project"
   • Enter project name (e.g., "Google Ads MCP")
   • Click "Create"

1.2 Enable Google Ads API

1. In your Google Cloud Console:
   • Go to "APIs & Services" → "Library"
   • Search for "Google Ads API"
   • Click on it and press "Enable"

1.3 Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"
3. Configure consent screen (if first time):
   • Click "Configure Consent Screen"
   • Choose "External" (unless you have Google Workspace)
   • Fill required fields:
     • App name: "Google Ads MCP"
     • User support email: Your email
     • Developer contact: Your email
   • Click "Save and Continue" through all steps
4. Create OAuth Client:
   • Application type: "Desktop application"
   • Name: "Google Ads MCP Client"
   • Click "Create"
5. Download credentials:
   • Click "Download JSON" button
   • Save file as client_secret_[long-string].json in your project directory

🔧 Step 2: Google Ads API Setup

2.1 Get Developer Token

1. Sign in to Google Ads
2. Go to Tools & Settings (wrench icon in top navigation)
3. Under "Setup", click "API Center"
4. Accept Terms of Service if prompted
5. Click "Apply for token"
6. Fill out application form:
   • Describe your use case (e.g., "MCP integration for campaign analysis")
   • Provide technical details about your implementation
7. Submit and wait for approval (usually 1-3 business days)

Note: You'll initially get a test token with limited functionality. After testing, you can apply for production access.

2.2 Find Your Developer Token

Once approved:

1. Return to API Center in Google Ads
2. Copy your Developer Token (format: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Step 3: Installation & Setup

3.1 Clone and Install

# Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3.2 Environment Configuration

Create a .env file in your project directory:

# Copy the example file
cp .env.example .env

Edit .env with your credentials:

# Required: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Example .env file:

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ Step 4: Claude Desktop Integration

4.1 Locate Claude Configuration

Find your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 Add MCP Server Configuration

Edit the configuration file and add your Google Ads MCP server:

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

Real Example:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

Important:

• Use absolute paths for all file locations
• On Windows, use forward slashes / or double backslashes \\ in paths
• Replace your_developer_token_here with your actual developer token

4.3 Restart Claude Desktop

Close and restart Claude Desktop to load the new configuration.

🔐 Step 5: First-Time Authentication

5.1 Trigger OAuth Flow

1. Open Claude Desktop
2. Try any Google Ads command, for example:

   "List all my Google Ads accounts"
   

5.2 Complete Authentication

1. Browser opens automatically to Google OAuth page
2. Sign in with your Google account (the one with Google Ads access)
3. Grant permissions by clicking "Allow"
4. Browser shows success page
5. Return to Claude - your command will complete automatically!

5.3 Verify Setup

After authentication, you should see:

• A google_ads_token.json file created in your project directory
• Your Google Ads accounts listed in Claude's response

📖 Usage Examples

Basic Account Operations

"List all my Google Ads accounts"

"Show me the account details and which ones have active campaigns"

Campaign Analysis

"Show me campaign performance for account 1234567890 in the last 30 days"

"Get conversion data for all campaigns in the last week"

"Which campaigns have the highest cost per conversion?"

Keyword Research

"Generate keyword ideas for 'digital marketing' using account 1234567890"

"Find keyword opportunities for 'AI automation' with search volume data"

"Research keywords for the page https://example.com/services"

Custom GAQL Queries

"Run this GAQL query for account 1234567890:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Get keyword performance data:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

🔍 Advanced GAQL Examples

Campaign Performance with Revenue

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Keyword Performance Analysis

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

Device Performance Breakdown

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

📁 Project Structure

google-ads-mcp-server/
├── server.py                           # Main MCP server
├── oauth/
│   ├── __init__.py                     # Package initialization
│   └── google_auth.py                  # OAuth authentication logic
├── google_ads_token.json               # Auto-generated token storage (gitignored)
├── client_secret_[long-string].json    # Your OAuth credentials (gitignored)
├── .env                                # Environment variables (gitignored)
├── .env.example                        # Environment template
├── .gitignore                          # Git ignore file
├── requirements.txt                    # Python dependencies
├── LICENSE                             # MIT License
└── README.md                           # This file

🔒 Security & Best Practices

File Security

• ✅ Credential files are gitignored - Never committed to version control
• ✅ Local token storage - Tokens stored in google_ads_token.json locally
• ✅ Environment variables - Sensitive data in .env file
• ✅ Automatic refresh - Minimal token exposure time

Recommended File Permissions

# Set secure permissions for sensitive files
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

Production Considerations

1. Use environment variables instead of .env files in production
2. Implement rate limiting to respect API quotas
3. Monitor API usage in Google Cloud Console
4. Secure token storage with proper access controls
5. Regular token rotation for enhanced security

🛠️ Troubleshooting

Authentication Issues

Issue	Symptoms	Solution
No tokens found	"Starting OAuth flow" message	✅ Normal for first-time setup - complete browser authentication
Token refresh failed	"Refreshing token failed" error	✅ Delete google_ads_token.json and re-authenticate
OAuth flow failed	Browser error or no response	Check credentials file path and internet connection
Permission denied	"Access denied" in browser	Ensure Google account has Google Ads access

Configuration Issues

Issue	Symptoms	Solution
Environment variables missing	"Environment variable not set"	Check .env file and Claude config env section
File not found	"FileNotFoundError"	Verify absolute paths in configuration
Module import errors	"ModuleNotFoundError"	Run pip install -r requirements.txt
Python path issues	"Command not found"	Use absolute path to Python executable

Claude Desktop Issues

Issue	Symptoms	Solution
Server not connecting	No Google Ads tools available	Restart Claude Desktop, check config file syntax
Invalid JSON config	Claude startup errors	Validate JSON syntax in config file
Permission errors	"Permission denied" on startup	Check file permissions and paths

API Issues

Issue	Symptoms	Solution
Invalid customer ID	"Customer not found"	Use 10-digit format without dashes: 1234567890
API quota exceeded	"Quota exceeded" error	Wait for quota reset or request increase
Invalid developer token	"Authentication failed"	Verify token in Google Ads API Center
GAQL syntax errors	"Invalid query"	Check GAQL syntax and field names

Debug Mode

Enable detailed logging for troubleshooting:

# Add to server.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

Getting Help

If you encounter issues:

1. Check the error message carefully - it usually indicates the exact problem
2. Verify all file paths are absolute and correct
3. Ensure environment variables are properly set
4. Check Google Cloud Console for API quotas and billing
5. Restart Claude Desktop after any configuration changes

🚀 Advanced Configuration

HTTP Transport Mode

For web deployment or remote access:

# Start server in HTTP mode
python3 server.py --http

Claude Desktop config for HTTP:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Custom Token Storage

Modify token storage location in oauth/google_auth.py:

# Custom token file location
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

Manager Account Configuration

For managing multiple accounts under an MCC:

# Add to .env file
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create development environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set up development environment
cp .env.example .env
# Add your development credentials to .env

Making Changes

1. Create a feature branch: git checkout -b feature/amazing-feature
2. Make your changes with appropriate tests
3. Test thoroughly with different account configurations
4. Update documentation as needed
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request with detailed description

Testing Your Changes

# Test authentication flow
python3 server.py --test-auth

# Test API connectivity
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ Authentication successful!')
"

# Test with Claude Desktop
# Add your server to Claude config and test various commands

📊 API Limits and Quotas

Google Ads API Quotas

• Basic access: 15,000 operations per day
• Standard access: 40,000 operations per day
• Request rate: 1,600 requests per minute per developer token

Best Practices for API Usage

1. Cache results when possible to reduce API calls
2. Use date ranges to limit data volume
3. Batch requests when supported
4. Monitor usage in Google Cloud Console
5. Implement retry logic for rate limit errors

Quota Management

# Monitor usage in Google Cloud Console
# Go to APIs & Services → Quotas
# Search for "Google Ads API" to see current usage

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

MIT License

Copyright (c) 2025 Google Ads MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📈 Roadmap

Upcoming Features

• 🔄 Enhanced keyword research with competitor analysis
• 📊 Built-in data visualization with charts and graphs
• 🤖 AI-powered optimization suggestions
• 📝 Campaign creation and management tools
• 🔍 Advanced reporting capabilities
• 🌐 Multi-language support

---

Made with ❤️ for the MCP community

Connect your Google Ads data directly to AI assistants and unlock powerful advertising insights through natural language conversations.