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/添加新工具
- 将工具定义添加到
_register_tools()在……里面tools.py - 实现处理程序方法
- 更新文档
调试
# 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许可证-有关详细信息，请参阅许可证文件
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 提交拉取请求
支持
对于问题和疑问：
- 检查 Google Ads API文档
- 查看错误消息和文档链接
- 在GitHub上打开一个问题