Google Ads API v20 MCP Server

Google Ads API v20 MCP服务器

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

特性

API全面覆盖

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

智能功能

• 自动重试逻辑：通过指数回退处理瞬态错误
• 错误文档：链接到官方谷歌广告API错误文档
• 部分故障处理：当某些操作失败时继续处理
• 令牌自动刷新：自动刷新OAuth令牌
• 自我重写：可以查找文档并重试失败的操作

安装

# Install with pip
pip install -e .

# Or install dependencies directly
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

配置

环境变量

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

# OAuth2 Authentication
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

# OR Service Account Authentication
GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com  # Optional

# Required for all auth methods
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890  # Manager account ID if applicable

配置文件

或者，在以下位置创建一个配置文件 ~/.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桌面配置(~/.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 all accounts
Use the list_accounts tool

# Create a campaign
Use create_campaign with customer_id="1234567890", name="Summer Sale 2025", 
budget_amount=100.0, campaign_type="SEARCH"

# Get campaign performance
Use get_campaign_performance with customer_id="1234567890", date_range="LAST_30_DAYS"

高级查询

# Run custom GAQL query
Use run_gaql_query with 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

性能最大功能（v20）

# Add negative keywords to Performance Max campaign
Use add_negative_keywords with customer_id="1234567890", 
campaign_id="123", keywords=["cheap", "discount", "free"]

错误处理

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

• 错误类型和代码
• 人类可读信息
• 错误是否可重试
• 官方文件链接
• 修复常见错误的建议

发展

运行测试

pytest tests/

添加新工具

1. 将工具定义添加到 _register_tools() 在……里面 tools.py
2. 实现处理程序方法
3. 更新文档

调试

# Run with debug logging
export LOG_LEVEL=DEBUG
python -m google-ads-mcp

安全说明

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

API版本支持

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

• Performance Max的活动级别负面关键字
• 通过渠道细分增强需求生成报告
• 平台可比转换
• 所有v20特定功能和改进

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 提交拉取请求

支持

对于问题和疑问：

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