Labsco
gomarble-ai logo

Google Ads

★ 131

from gomarble-ai

MCP server acting as an interface to the Google Ads, enabling programmatic access to Google Ads data and management features.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#social-media#slack#payments#cloud#devops#git

Google Ads MCP Server 🚀

License: MIT Python 3.10+ FastMCP

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.

<video controls width="1920" height="512" src="https://github.com/user-attachments/assets/1dc62f47-ace4-4dcf-8009-593ef7194b43">Your browser does not support the video tag.</video>

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

ToolDescriptionParametersExample Usage
list_accountsList all accessible Google Ads accountsNone"List all my Google Ads accounts"
run_gaqlExecute GAQL queries with custom formattingcustomer_id, query, manager_id (optional)"Show me campaign performance for account 1234567890"
run_keyword_plannerGenerate keyword ideas with metricscustomer_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!

🖥️ Step 4: Claude Desktop Integration

4.1 Locate Claude Configuration

Find your Claude Desktop configuration file:

macOS:

Copy & paste — that's it
~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

Copy & paste — that's it
%APPDATA%\Claude\claude_desktop_config.json

4.2 Add MCP Server Configuration

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

Copy & paste — that's it
{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

Real Example:

Copy & paste — that's it
{
  "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:
    Copy & paste — that's it
    "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

🔍 Advanced GAQL Examples

Campaign Performance with Revenue

Copy & paste — that's it
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

Copy & paste — that's it
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

Copy & paste — that's it
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

Copy & paste — that's it
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

Copy & paste — that's it
# 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

🤝 Contributing

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

Development Setup

Copy & paste — that's it
# 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

Copy & paste — that's it
# 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

Copy & paste — that's it
# 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

Copy & paste — that's it
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.