Google Ads API v20 MCP 服务器

一个全面的模型上下文协议（MCP）服务器，提供对 Google Ads API v20 功能的完全访问。此服务器使AI助手能够通过自然语言命令执行任何 Google Ads 操作。

特性

完整的API覆盖

• 账户管理：列出账户，获取账户信息，查看层次结构
• 活动管理：创建、更新、暂停/恢复活动，包括所有 v20 特性
• 广告组管理：广告组的全部 CRUD 操作
• 广告创建：响应式搜索广告、扩展文本广告等
• 资产管理：上传和管理图像、文本资产
• 预算管理：创建和管理共享预算
• 关键词管理：添加关键词、否定关键词（包括 Performance Max 活动级别的否定关键词）
• 报告与分析：自定义 GAQL 查询、性能报告、搜索词
• 高级特性：建议、变更历史、实验

智能特性

• 自动重试逻辑：处理瞬时错误时采用指数退避
• 错误文档：链接到官方 Google Ads API 错误文档
• 部分失败处理：当某些操作失败时继续处理
• 令牌自动刷新：自动刷新 OAuth 令牌
• 自我重写：可以查找文档并重试失败的操作

安装

# 使用 pip 安装
pip install -e .

# 或者直接安装依赖项
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

配置

环境变量

创建一个 .env 文件或设置这些环境变量：

# OAuth2 认证
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

# 或者服务账户认证
GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com  # 可选

# 所有认证方法都需要
GOOGLE_AADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890  # 如适用，请填写管理账户ID

配置文件

或者，在 ~/.config/google-ads-mcp/config.json 创建一个配置文件：

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "your_refresh_token",
  "developer_token": "your_developer_token",
  "login_customer_id": "1234567890"
}

MCP 配置

添加到你的 Claude Desktop 配置 (~/.config/claude/mcp.json)：

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

使用示例

基本操作

# 列出所有账户
使用 list_accounts 工具

# 创建一个活动
使用 create_campaign，参数为 customer_id="1234567890"，name="夏季促销2025"，
budget_amount=100.0，campaign_type="SEARCH"

# 获取活动表现
使用 get_campaign_performance，参数为 customer_id="1234567890"，date_range="LAST_30_DAYS"

高级查询

# 运行自定义 GAQL 查询
使用 run_gaql_query，参数为 query：
SELECT campaign.name, metrics.clicks, metrics.conversions
FROM campaign
WHERE metrics.impressions > 1000
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.clicks DESC

Performance Max 功能（v20）

# 向 Performance Max 活动添加否定关键词
使用 add_negative_keywords，参数为 customer_id="1234567890"，
campaign_id="123"，keywords=["便宜", "折扣", "免费"]

错误处理

该服务器提供了详细的错误信息：

• 错误类型和代码
• 可读性强的消息
• 是否可重试
• 链接到官方文档
• 解决常见错误的建议

开发

运行测试

pytest tests/

添加新工具

1. 在 tools.py 的 _register_tools() 中添加工具定义
2. 实现处理器方法
3. 更新文档

调试

# 使用调试日志运行
export LOG_LEVEL=DEBUG
python -m google-ads-mcp

安全注意事项

• 不要将凭据提交到版本控制中
• 生产环境中使用服务账户
• 在 Google Ads 账户上启用双因素认证
• 定期轮换刷新令牌
• 监控 API 使用情况并设置警报

API 版本支持

此服务器是为 Google Ads API v20（2025年6月发布）构建的，并包括：

• Performance Max 活动级别的否定关键词
• 带有渠道细分的增强型需求生成报告
• 平台可比较转化
• 所有 v20 特定功能和改进

许可

MIT 许可证 - 详情见 LICENSE 文件

贡献

欢迎贡献！请：

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

支持

对于问题和疑问：

• 查看 Google Ads API 文档
• 查阅错误消息和文档链接
• 在 GitHub 上打开一个问题