Google Ads Mcp Server

Google Ads MCP 服务 🚀

一个由 FastMCP 驱动、用于 Google Ads API 集成并支持自动 OAuth 2.0 认证的 Model Context Protocol 服务

通过无缝的 OAuth 2.0 认证、自动令牌刷新、GAQL 查询和关键词研究能力，将 Google Ads API 直接连接到 Claude Desktop 及其他 MCP 客户端。

您的浏览器不支持 video 标签。

轻松一键安装

为获得更简单的安装体验，我们提供开箱即用的安装程序：

👉 下载安装程序 - https://gomarble.ai/mcp

加入我们的社区，获取帮助和最新动态

👉 Slack 社区 - AI in Ads

也试试 Facebook 广告 MCP 服务

👉 Facebook Ads MCP - Facebook Ads MCP

✨ 功能特性

• 🔐 自动 OAuth 2.0 - 一次性浏览器认证，自动刷新
• 🔄 智能令牌管理 - 自动处理过期的令牌
• 📊 GAQL 查询执行 - 运行任意 Google Ads Query Language 查询
• 🏢 账号管理 - 列出并管理 Google Ads 账号
• 🔍 关键词研究 - 生成带搜索量数据的关键词创意
• 🚀 FastMCP 框架 - 基于现代 MCP 标准构建
• 🖥️ Claude Desktop 就绪 - 与 Claude Desktop 直接集成
• 🛡️ 安全的本地存储 - 令牌存储在本地，绝不外泄

📋 可用工具

工具	描述	参数	示例用法
list_accounts	列出所有可访问的 Google Ads 账号	无	"List all my Google Ads accounts"
run_gaql	执行带自定义格式的 GAQL 查询	customer_id、query、manager_id（可选）	"Show me campaign performance for account 1234567890"
run_keyword_planner	生成带指标的关键词创意	customer_id、keywords、manager_id、page_url、日期范围选项	"Generate keyword ideas for 'digital marketing'"

注意： 所有工具都会自动处理认证 - 无需令牌参数！

🚀 快速开始

前置条件

在设置 MCP 服务之前，您需要：

• 已安装 Python 3.10+
• 一个 Google Cloud Platform 账号
• 一个拥有 API 访问权限的 Google Ads 账号

🔧 第 1 步：Google Cloud Platform 设置

1.1 创建 Google Cloud 项目

1. 前往 Google Cloud Console
2. 创建一个新项目：
   • 点击 "Select a project" → "New Project"
   • 输入项目名称（例如 "Google Ads MCP"）
   • 点击 "Create"

1.2 启用 Google Ads API

1. 在您的 Google Cloud Console 中：
   • 前往 "APIs & Services" → "Library"
   • 搜索 "Google Ads API"
   • 点击它并按下 "Enable"

1.3 创建 OAuth 2.0 凭据

1. 前往 "APIs & Services" → "Credentials"
2. 点击 "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"
3. 配置同意屏幕（如果是首次）：
   • 点击 "Configure Consent Screen"
   • 选择 "External"（除非您拥有 Google Workspace）
   • 填写必填字段：
     • 应用名称："Google Ads MCP"
     • 用户支持邮箱：您的邮箱
     • 开发者联系方式：您的邮箱
   • 在所有步骤中点击 "Save and Continue"
4. 创建 OAuth 客户端：
   • 应用类型："Desktop application"
   • 名称："Google Ads MCP Client"
   • 点击 "Create"
5. 下载凭据：
   • 点击 "Download JSON" 按钮
   • 将文件保存为 client_secret_[long-string].json，放在您的项目目录中

🔧 步骤 2：Google Ads API 设置

2.1 获取开发者令牌

1. 登录 Google Ads
2. 前往工具与设置（顶部导航中的扳手图标）
3. 在“设置”下，点击“API Center”
4. 如出现提示，接受服务条款
5. 点击“Apply for token”
6. 填写申请表：
   • 描述你的用例（例如：“用于广告系列分析的 MCP 集成”）
   • 提供有关你的实现的技术细节
7. 提交并等待审批（通常为 1-3 个工作日）

注意： 你最初会获得一个功能受限的测试令牌。测试完成后，你可以申请生产环境访问权限。

2.2 找到你的开发者令牌

审批通过后：

1. 返回 Google Ads 中的 API Center
2. 复制你的开发者令牌（格式：XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX）

🔧 步骤 3：安装与设置

3.1 克隆并安装

# 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 环境配置

在你的项目目录中创建 .env 文件：

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

使用你的凭据编辑 .env：

# 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

示例 .env 文件：

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

🖥️ 步骤 4：Claude Desktop 集成

4.1 找到 Claude 配置文件

找到你的 Claude Desktop 配置文件：

macOS：

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

Windows：

%APPDATA%\Claude\claude_desktop_config.json

4.2 添加 MCP 服务配置

编辑配置文件并添加你的 Google Ads MCP 服务：

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

真实示例：

{
  "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"
      ]
    }
  }
}

重要：

• 所有文件位置都使用绝对路径
• 在 Windows 上，路径中使用正斜杠 / 或双反斜杠 \\
• 将 your_developer_token_here 替换为你的实际开发者令牌

4.3 重启 Claude Desktop

关闭并重启 Claude Desktop 以加载新配置。

🔐 步骤 5：首次身份验证

5.1 触发 OAuth 流程

1. 打开 Claude Desktop
2. 尝试任意 Google Ads 命令，例如：

   "List all my Google Ads accounts"
   

5.2 完成身份验证

1. 浏览器自动打开 Google OAuth 页面
2. 登录你的 Google 账号（具有 Google Ads 访问权限的账号）
3. 授予权限，点击“Allow”
4. 浏览器显示成功页面
5. 返回 Claude - 你的命令将自动完成！

5.3 验证设置

身份验证后，你应该会看到：

• 在你的项目目录中创建了 google_ads_token.json 文件
• 你的 Google Ads 账号列在 Claude 的响应中

📖 使用示例

基础账号操作

"List all my Google Ads accounts"

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

广告系列分析

"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?"

关键词研究

"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"

自定义 GAQL 查询

"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"

🔍 高级 GAQL 示例

带收入的广告系列效果

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

关键词效果分析

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

设备效果细分

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'

📁 项目结构

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

🔒 安全与最佳实践

文件安全

• ✅ 凭据文件已被 gitignore - 绝不提交到版本控制
• ✅ 本地令牌存储 - 令牌本地存储在 google_ads_token.json 中
• ✅ 环境变量 - 敏感数据存放在 .env 文件中
• ✅ 自动刷新 - 令牌暴露时间最短

推荐的文件权限

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

生产环境注意事项

1. 在生产环境中使用环境变量，而不是 .env 文件
2. 实现速率限制，以遵守 API 配额
3. 在 Google Cloud Console 中监控 API 使用情况
4. 通过适当的访问控制保护令牌存储
5. 定期轮换令牌以增强安全性

🛠️ 故障排查

身份验证问题

问题	症状	解决方案
未找到令牌	“Starting OAuth flow”消息	✅ 首次设置时属正常 - 完成浏览器身份验证
令牌刷新失败	“Refreshing token failed”错误	✅ 删除 google_ads_token.json 并重新进行身份验证
OAuth 流程失败	浏览器错误或无响应	检查凭据文件路径和互联网连接
权限被拒绝	浏览器显示“Access denied”	确保 Google 账号具有 Google Ads 访问权限

配置问题

问题	症状	解决方案
环境变量缺失	"Environment variable not set"	检查 .env 文件和 Claude 配置中的 env 部分
文件未找到	"FileNotFoundError"	验证配置中的绝对路径
模块导入错误	"ModuleNotFoundError"	运行 pip install -r requirements.txt
Python 路径问题	"Command not found"	使用 Python 可执行文件的绝对路径

Claude Desktop 问题

问题	症状	解决方案
服务无法连接	没有可用的 Google Ads 工具	重启 Claude Desktop，检查配置文件语法
无效的 JSON 配置	Claude 启动错误	验证配置文件中的 JSON 语法
权限错误	启动时出现 "Permission denied"	检查文件权限和路径

API 问题

问题	症状	解决方案
无效的客户 ID	"Customer not found"	使用不带短横线的 10 位格式：1234567890
API 配额超限	"Quota exceeded" 错误	等待配额重置或申请提高配额
无效的开发者令牌	"Authentication failed"	在 Google Ads API Center 中验证令牌
GAQL 语法错误	"Invalid query"	检查 GAQL 语法和字段名称

调试模式

启用详细日志记录以进行故障排查：

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

获取帮助

如果遇到问题：

1. 仔细检查错误消息 - 它通常会指出确切的问题
2. 验证所有文件路径是否为绝对路径且正确
3. 确保环境变量已正确设置
4. 检查 Google Cloud Console 中的 API 配额和账单
5. 重启 Claude Desktop 以应用任何配置更改

🚀 高级配置

HTTP 传输模式

用于 Web 部署或远程访问：

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

HTTP 的 Claude Desktop 配置：

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

自定义令牌存储

在 oauth/google_auth.py 中修改令牌存储位置：

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

经理账户配置

用于管理 MCC 下的多个账户：

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

🤝 贡献

我们欢迎贡献！以下是入门方法：

开发环境设置

# 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

进行更改

1. 创建功能分支： git checkout -b feature/amazing-feature
2. 进行更改并添加适当的测试
3. 彻底测试不同的账户配置
4. 更新文档（如需要）
5. 提交更改： git commit -m 'Add amazing feature'
6. 推送到分支： git push origin feature/amazing-feature
7. 打开 Pull Request 并附上详细描述

测试你的更改

# 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 限制和配额

Google Ads API 配额

• 基本访问权限： 每天 15,000 次操作
• 标准访问权限： 每天 40,000 次操作
• 请求速率： 每个开发者令牌每分钟 1,600 次请求

API 使用最佳实践

1. 尽可能缓存结果以减少 API 调用
2. 使用日期范围限制数据量
3. 在支持的情况下批量请求
4. 在 Google Cloud Console 中监控使用情况
5. 为速率限制错误实现重试逻辑

配额管理

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

📄 许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

---

MIT 许可证

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.

📈 路线图

即将推出的功能

• 🔄 增强的关键词研究，包含竞争对手分析
• 📊 内置数据可视化，包含图表和图形
• 🤖 AI 驱动的优化建议
• 📝 广告系列创建和管理工具
• 🔍 高级报告功能
• 🌐 多语言支持

---

用 ❤️ 为 MCP 社区打造

将你的 Google Ads 数据直接连接到 AI 助手，通过自然语言对话解锁强大的广告洞察。