谷歌广告MCP服务器
项目介绍
Google Ads MCP Server 🚀
一个基于FastMCP的模型上下文协议服务器，用于与Google Ads API集成，并自动进行OAuth 2.0认证
直接连接Google Ads API到Claude Desktop和其他MCP客户端，具有无缝的OAuth 2.0认证、自动令牌刷新、GAQL查询和关键词研究能力。
<video controls width="1920" height="512" src="https://github.com/user-attachments/assets/1dc62f47-ace4-4dcf-8009-593ef7194b43">您的浏览器不支持视频标签。</video>
简单的一键设置
为了更简单的设置体验，我们提供了现成的安装程序：
👉 下载安装程序 - https://gomarble.ai/mcp
加入我们的社区获取帮助和更新
👉 Slack 社区 - AI in Ads
尝试Facebook广告MCP服务器
👉 Facebook Ads MCP - Facebook Ads MCP
✨ 特性
- 🔐 自动OAuth 2.0 - 一次浏览器认证，自动刷新
- 🔄 智能令牌管理 - 自动处理过期令牌
- 📊 GAQL查询执行 - 运行任何Google Ads查询语言查询
- 🏢 账户管理 - 列出并管理Google Ads账户
- 🔍 关键词研究 - 生成带有搜索量数据的关键词建议
- 🚀 FastMCP框架 - 基于现代MCP标准构建
- 🖥️ Claude Desktop就绪 - 直接集成到Claude Desktop
- 🛡️ 安全本地存储 - 令牌本地存储，永不暴露
📋 可用工具
| 工具 | 描述 | 参数 | 示例用法 |
|---|---|---|---|
list_accounts | 列出所有可访问的Google Ads账户 | 无 | "列出我所有的Google Ads账户" |
run_gaql | 执行带有自定义格式的GAQL查询 | customer_id, query, manager_id (可选) | "显示账户1234567890的活动表现" |
run_keyword_planner | 生成带有指标的关键词建议 | customer_id, keywords, manager_id, page_url, 日期范围选项 | "为'digital marketing'生成关键词建议" |
注意： 所有工具都会自动处理认证 - 不需要提供令牌参数！
🚀 快速开始
先决条件
在设置MCP服务器之前，您需要：
- 安装Python 3.10+
- 一个Google Cloud Platform账户
- 一个具有API访问权限的Google Ads账户
🔧 第一步：Google Cloud Platform设置
1.1 创建Google Cloud项目
- 前往Google Cloud控制台
- 创建新项目：
- 点击“选择项目” → “新建项目”
- 输入项目名称（例如，“Google Ads MCP”）
- 点击“创建”
1.2 启用Google Ads API
- 在您的Google Cloud控制台中：
- 转到“API和服务” → “库”
- 搜索“Google Ads API”
- 点击它并点击“启用”
1.3 创建OAuth 2.0凭证
- 转到“API和服务” → “凭证”
- 点击“+ 创建凭证” → “OAuth 2.0客户端ID”
- 配置同意屏幕（如果是第一次）：
- 点击“配置同意屏幕”
- 选择“外部”（除非您有Google Workspace）
- 填写所需字段：
- 应用名称：“Google Ads MCP”
- 用户支持电子邮件：您的电子邮件
- 开发者联系：您的电子邮件
- 点击“保存并继续”完成所有步骤
- 创建OAuth客户端：
- 应用类型：“桌面应用”
- 名称：“Google Ads MCP客户端”
- 点击“创建”
- 下载凭证：
- 点击“下载JSON”按钮
- 将文件保存为
client_secret_[长字符串].json在您的项目目录中
🔧 第二步：Google Ads API设置
2.1 获取开发者令牌
- 登录到Google Ads
- 转到工具和设置（顶部导航中的扳手图标）
- 在“设置”下，点击“API中心”
- 如果提示，请接受服务条款
- 点击“申请令牌”
- 填写申请表：
- 描述您的使用案例（例如，“MCP集成用于活动分析”）
- 提供关于您的实现的技术细节
- 提交并等待审批（通常1-3个工作日）
注意： 您最初会获得一个具有有限功能的测试令牌。测试后，您可以申请生产访问权限。
2.2 查找您的开发者令牌
一旦批准：
- 返回Google Ads中的API中心
- 复制您的开发者令牌（格式：
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX）
🔧 第三步：安装与设置
3.1 克隆并安装
# 克隆仓库
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server
# 创建虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate # 在Windows上：.venv\Scripts\activate
# 安装依赖项
pip install -r requirements.txt
3.2 环境配置
在您的项目目录中创建一个.env文件：
# 复制示例文件
cp .env.example .env
编辑.env文件以包含您的凭据：
# 必需：Google Ads API开发者令牌
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
# 必需：OAuth凭证JSON文件的路径（从Google Cloud下载）
GOOGLE_ADS_OAUTH_CONFIG_PATH=/完整路径/到你的/client_secret_file.json
示例.env文件：
GOOGLE_A_开发人员_TOKEN=ABCDEFG1234567890
GOOGLE_A_开发人员_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json
🖥️ 第四步：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": "/完整路径/到你的/project/.venv/bin/python",
"args": [
"/完整路径/到你的/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.1 触发OAuth流程
- 打开Claude Desktop
- 尝试任何Google Ads命令，例如：
"列出我所有的Google Ads账户"
5.2 完成认证
- 浏览器会自动打开到Google OAuth页面
- 使用您的Google账户登录（具有Google Ads访问权限的那个）
- 通过点击“允许”授予权限
- 浏览器显示成功页面
- 返回Claude - 您的命令将自动完成！
5.3 验证设置
认证后，您应该看到：
- 在您的项目目录中创建了一个
google_ads_token.json文件 - 您的Google Ads账户列在Claude的响应中
📖 使用示例
基本账户操作
"列出我所有的Google Ads账户"
"显示账户详情以及哪些账户有活动的活动"
活动分析
"显示账户1234567890在过去30天内的活动表现"
"获取所有活动在过去一周的转化数据"
"哪些活动的每次转化成本最高？"
关键词研究
"为'digital marketing'生成关键词建议，使用账户1234567890"
"查找带有搜索量数据的'AI自动化'关键词机会"
"研究页面https://example.com/services的关键词"
自定义GAQL查询
"运行此GAQL查询，针对账户1234567890：
SELECT campaign.name, metrics.clicks, metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_7_DAYS"
"获取关键词表现数据：
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 # 主MCP服务器
├── oauth/
│ ├── __init__.py # 包初始化
│ └── google_auth.py # OAuth认证逻辑
├── google_ads_token.json # 自动生成的令牌存储（已忽略）
├── client_secret_[长字符串].json # 您的OAuth凭证（已忽略）
├── .env # 环境变量（已忽略）
├── .env.example # 环境模板
├── .gitignore # Git忽略文件
├── requirements.txt # Python依赖项
├── LICENSE # MIT许可证
└── README.md # 此文件
🔒 安全与最佳实践
文件安全
- ✅ 凭证文件被忽略 - 从未提交到版本控制
- ✅ 本地令牌存储 - 令牌存储在
google_ads_token.json本地 - ✅ 环境变量 - 敏感数据在
.env文件中 - ✅ 自动刷新 - 最小化令牌暴露时间
推荐文件权限
# 设置敏感文件的安全权限
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json
生产考虑
- 使用环境变量而不是
.env文件在生产环境中 - 实现速率限制以尊重API配额
- 监控API使用情况在Google Cloud控制台
- 安全令牌存储使用适当的访问控制
- 定期令牌轮换以增强安全性
🛠️ 故障排除
认证问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 未找到令牌 | "开始OAuth流程"消息 | ✅ 对于初次设置正常 - 完成浏览器认证 |
| 令牌刷新失败 | "刷新令牌失败"错误 | ✅ 删除google_ads_token.json并重新认证 |
| OAuth流程失败 | 浏览器错误或无响应 | 检查凭证文件路径和互联网连接 |
| 权限被拒绝 | 浏览器中的"访问被拒绝" | 确保Google账户具有Google Ads访问权限 |
配置问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 缺少环境变量 | "环境变量未设置" | 检查.env文件和Claude配置env部分 |
| 文件未找到 | "FileNotFoundError" | 验证配置中的绝对路径 |
| 模块导入错误 | "ModuleNotFoundError" | 运行pip install -r requirements.txt |
| Python路径问题 | "命令未找到" | 使用Python可执行文件的绝对路径 |
Claude Desktop问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 服务器无法连接 | 没有可用的Google Ads工具 | 重启Claude Desktop，检查配置文件语法 |
| 无效的JSON配置 | Claude启动错误 | 验证配置文件中的JSON语法 |
| 权限错误 | 启动时"权限被拒绝" | 检查文件权限和路径 |
API问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 无效客户ID | "找不到客户" | 使用不带破折号的10位格式：1234567890 |
| API配额超出 | "配额超出"错误 | 等待配额重置或请求增加 |
| 无效开发者令牌 | "身份验证失败" | 在Google Ads API中心验证令牌 |
| GAQL语法错误 | "无效查询" | 检查GAQL语法和字段名称 |
调试模式
启用详细的日志记录以进行故障排除：
# 添加到server.py以调试
import logging
logging.basicConfig(level=logging.DEBUG)
获取帮助
如果您遇到问题：
- 仔细检查错误信息 - 它通常指示确切的问题
- 验证所有文件路径是绝对且正确的
- 确保环境变量正确设置
- 检查Google Cloud控制台的API配额和计费
- 在任何配置更改后重启Claude Desktop
🚀 高级配置
HTTP传输模式
对于Web部署或远程访问：
# 以HTTP模式启动服务器
python3 server.py --http
Claude Desktop配置为HTTP：
{
"mcpServers": {
"google-ads": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
自定义令牌存储
修改oauth/google_auth.py中的令牌存储位置：
# 自定义令牌文件位置
def get_token_path():
return "/custom/secure/path/google_ads_token.json"
管理员账户配置
用于管理多个账户下的MCC：
# 添加到.env文件
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890
🤝 贡献
我们欢迎贡献！以下是开始的方法：
开发设置
# 分叉并克隆仓库
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server
# 创建开发环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
# 设置开发环境
cp .env.example .env
# 将您的开发凭据添加到.env
进行更改
- 创建特性分支：
git checkout -b feature/amazing-feature - 进行您的更改并附带适当的测试
- 彻底测试不同的账户配置
- 根据需要更新文档
- 提交更改：
git commit -m '添加惊人的功能' - 推送到分支：
git push origin feature/amazing-feature - 打开带有详细描述的拉取请求
测试您的更改
# 测试认证流程
python3 server.py --test-auth
# 测试API连接
python3 -c "
from