使用说明
谷歌广告MCP服务器
使用官方Python SDK的Google Ads API的非官方模型上下文协议（MCP）服务器实现。
概述
该项目提供了一个MCP服务器，该服务器包装了Google Ads API v20，使大型语言模型（LLM）能够通过标准化界面与Google Ads帐户进行交互。服务器使用带有完整类型注释的官方Google Ads Python SDK，实现健壮可靠的API交互。
特性
- 全类型安全：使用pyright通过严格的类型注释实现
- 基于SDK：基于官方Google Ads Python SDK构建，具有可靠性
- 全面覆盖：实施89项谷歌广告服务进行广告活动管理
- 符合MCP标准：遵循LLM集成的模型上下文协议规范
- 异步支持：利用FastMCP进行异步操作
- 广泛的测试覆盖范围：72项服务具有测试覆盖率
安装
git clone https://github.com/promobase/google-ads-mcp.git
cd google-ads-mcp
# Install dependencies using uv
uv sync
# Set up Google Ads credentials
export GOOGLE_ADS_DEVELOPER_TOKEN="your_developer_token"
export GOOGLE_ADS_CLIENT_ID="your_client_id"
export GOOGLE_ADS_CLIENT_SECRET="your_client_secret"
export GOOGLE_ADS_REFRESH_TOKEN="your_refresh_token"
用法
uv run main.py
特征奇偶校验表
下面是一个综合表格，显示了Google Ads API v20服务在该MCP服务器中的实施状态：
| 服务名称 | 类别 | 已实施 | 测试覆盖率 | 备注 |
|---|---|---|---|---|
| 核心活动管理 | ||||
| 活动服务 | 活动 | ✅ 是 | ✅ 是 | 核心活动CRUD操作 |
| 预算服务 | 活动 | ✅ 是 | ✅ 是 | 预算管理 |
| AdGroupService | 活动 | ✅ 是 | ✅ 是 | 广告组管理 |
| AdGroupAdService | 活动 | ✅ 是 | ✅ 是 | 广告到广告组关联 |
| 广告服务 | 活动 | ✅ 是 | ✅ 是 | 广告创建和管理 |
| 关键字服务 | 活动 | ✅ 是 | ✅ 是 | 关键字管理 |
| 投标和预算 | ||||
| 投标策略服务 | 投标 | ✅ 是 | ✅ 是 | 自动竞价策略 |
| 投标数据排除服务 | 投标 | ✅ 是 | ✅ 是 | 投标数据排除 |
| 投标季节性调整服务 | 投标 | ✅ 是 | ❌ 否 | 季节性投标调整 |
| CampaignBidModifier服务 | 投标 | ✅ 是 | ✅ 是 | 活动出价调整 |
| AdGroupBidModifier服务 | 竞价 | ✅ 是 | ✅ 是 | 广告组出价调整 |
| 会计预算提案服务 | 预算 | ✅ 是 | ✅ 是 | 账户预算提案 |
| 目标和标准 | ||||
| 活动标准服务 | 目标定位 | ✅ 是 | ✅ 是 | 活动级别目标 |
| AdGroupCriterionService | 目标定位 | ✅ 是 | ✅ 是 | 广告组级别定位 |
| 客户负面标准服务 | 目标定位 | ✅ 是 | ❌ 否 | 帐户级别排除 |
| GeoTargetConstantService | 目标定位 | ✅ 是 | ✅ 是 | 地理定位 |
| 资产和扩展 | ||||
| 资产服务 | 资产 | ✅ 是 | ✅ 是 | 图像、文本、视频资源 |
| AssetGroup服务 | 资产 | ✅ 是 | ✅ 是 | 性能最大资产组 |
| 资产组资产服务 | 资产 | ✅ 是 | ✅ 是 | 资产组资产链接 |
| AssetGroup信号服务 | 资产 | ✅ 是 | ✅ 是 | 资产组信号 |
| CampaignAssetService | 资产 | ✅ 是 | ✅ 是 | 活动级资产链接 |
| CampaignAssetSetService | 资产 | ✅ 是 | ✅ 是 | 活动资产集链接 |
| AssetSetService | 资产 | ✅ 是 | ✅ 是 | 资产集管理 |
| AdGroupAssetService | 资产 | ✅ 是 | ✅ 是 | 广告组级资产链接 |
| AdGroupAssetSetService | 资产 | ✅ 是 | ❌ 否 | 广告组资产集链接 |
| 客户资产服务 | 资产 | ✅ 是 | ✅ 是 | 客户级资产链接 |
| 观众与再营销 | ||||
| 用户列表服务 | 受众 | ✅ 是 | ✅ 是 | 再营销列表 |
| CustomInterestService | 观众 | ✅ 是 | ✅ 是 | 自定义兴趣受众 |
| CustomAudienceService | 观众 | ✅ 是 | ✅ 是 | 自定义受众细分 |
| 再营销行动服务 | 观众 | ✅ 是 | ✅ 是 | 再营销标签 |
| 观众服务 | 观众 | ✅ 是 | ✅ 是 | 组合观众 |
| 观众洞察服务 | 观众 | ✅ 是 | ✅ 是 | 受众分析和见解 |
| 转换和测量 | ||||
| 转换服务 | 转换 | ✅ 是 | ✅ 是 | 转换跟踪 |
| 转换上传服务 | 转换 | ✅ 是 | ✅ 是 | 离线转换上传 |
| 转换调整上传服务 | 转换 | ✅ 是 | ❌ 否 | 转换调整 |
| ConversionValueRuleService | 转换 | ✅ 是 | ❌ 否 | 值规则 |
| ConversionCustomVariableService | 转换 | ✅ 是 | ✅ 是 | 自定义转换变量 |
| 转换GoalCampaignConfigService | 转换 | ✅ 是 | ✅ 是 | 活动转化目标 |
| 客户转化目标服务 | 转化 | ✅ 是 | ✅ 是 | 客户转化目标 |
| 自定义转换目标服务 | 转换 | ✅ 是 | ❌ 否 | 自定义转换目标 |
| 账户管理 | ||||
| 客户服务 | 帐户 | ✅ 是 | ✅ 是 | 帐户信息 |
| 客户用户访问服务 | 帐户 | ✅ 是 | ✅ 是 | 用户访问管理 |
| 客户用户访问邀请服务 | 帐户 | ✅ 是 | ❌ 否 | 访问邀请 |
| 客户客户端链接服务 | 帐户 | ✅ 是 | ✅ 是 | 经理帐户链接 |
| 客户管理器链接服务 | 帐户 | ✅ 是 | ✅ 是 | 管理器链接管理 |
| AccountLinkService | 帐户 | ✅ 是 | ✅ 是 | 第三方帐户链接 |
| 计费设置服务 | 帐户 | ✅ 是 | ✅ 是 | 计费配置 |
| 发票服务 | 账户 | ✅ 是 | ✅ 是 | 开具发票 |
| 付款账户服务 | 账户 | ✅ 是 | ❌ 否 | 付款账户信息 |
| 身份验证服务 | 帐户 | ✅ 是 | ❌ 否 | 身份验证 |
| 标签和组织 | ||||
| LabelService | 组织 | ✅ 是 | ✅ 是 | 标签管理 |
| CampaignLabelService | 组织 | ✅ 是 | ✅ 是 | 活动标签关联 |
| AdGroupLabelService | 组织 | ✅ 是 | ✅ 是 | 广告组标签关联 |
| AdGroupAdLabelService | 组织 | ✅ 是 | ❌ 无 | 广告标签关联 |
| AdGroupCriterionLabelService | 组织 | ✅ 是 | ✅ 是 | 标准标签关联 |
| 客户标签服务 | 组织 | ✅ 是 | ✅ 是 | 客户标签关联 |
| SharedSet服务 | 组织 | ✅ 是 | ✅ 是 | 共享负面列表 |
| 共享标准服务 | 组织 | ✅ 是 | ❌ 否 | 共享标准 |
| CampaignSharedSet服务 | 组织 | ✅ 是 | ✅ 是 | 活动共享集链接 |
| 智能活动 | ||||
| SmartCampaignService | 智能 | ✅ 是 | ✅ 是 | 智能活动管理 |
| SmartCampaignSettings服务 | 智能 | ❌ 否 | ❌ 否 | 智能活动设置 |
| SmartCampaign建议服务 | 智能 | ❌ 否 | ❌ 否 | 智能活动建议 |
| 实验与测试 | ||||
| 实验服务 | 测试 | ✅ 是 | ✅ 是 | 活动实验 |
| 实验武器服务 | 测试 | ✅ 是 | ✅ 是 | 实验变化 |
| CampaignDraftService | 测试 | ✅ 是 | ✅ 是 | 活动草稿 |
| 规划工具 | ||||
| 关键字计划服务 | 计划 | ✅ 是 | ✅ 是 | 关键字规划 |
| 关键词策划活动服务 | 策划 | ✅ 是 | ✅ 是 | 关键字计划活动 |
| 关键词策划活动关键词服务 | 策划 | ✅ 是 | ✅ 是 | 计划中的活动关键字 |
| 关键字计划AdGroup服务 | 计划 | ✅ 是 | ✅ 是 | 关键字计划广告组 |
| 关键字计划AdGroup关键字服务 | 计划 | ✅ 是 | ✅ 是 | 计划中的广告组关键字 |
| 关键词规划创意服务 | 规划 | ✅ 是 | ✅ 是 | 关键词创意 |
| ReachPlanService | 规划 | ✅ 是 | ✅ 是 | 达成计划 |
| 建议 | ||||
| 推荐服务 | 优化 | ✅ 是 | ✅ 是 | 帐户推荐 |
| 推荐订阅服务 | 优化 | ❌ 否 | ❌ 否 | 推荐订阅 |
| 元数据和发现 | ||||
| GoogleAdsFieldService | 元数据 | ✅ 是 | ✅ 是 | 字段元数据 |
| 谷歌广告服务 | 核心 | ✅ 是 | ✅ 是 | 搜索操作（GAQL） |
| 搜索服务 | 核心 | ✅ 是 | ✅ 是 | 备选搜索界面 |
| 高级功能 | ||||
| BatchJobService | 批量操作 | ✅ 是 | ✅ 是 | 批量操作 |
| 离线用户数据作业服务 | 数据导入 | ✅ 是 | ❌ 否 | 客户匹配 |
| UserDataService | 数据导入 | ✅ 是 | ✅ 是 | 增强转换 |
| 自定义属性服务 | 自定义 | ✅ 是 | ❌ 否 | 广告定制商 |
| 活动定制服务 | 定制 | ✅ 是 | ✅ 是 | 活动定制者 |
| AdGroup定制服务 | 定制 | ✅ 是 | ✅ 是 | 广告组定制商 |
| AdGroup标准定制服务 | 定制 | ✅ 是 | ✅ 是 | 标准定制者 |
| 客户定制服务 | 定制 | ✅ 是 | ❌ 否 | 客户定制商 |
| AdParameterService | 自定义 | ✅ 是 | ✅ 是 | 广告参数 |
| 数据链路服务 | 集成 | ✅ 是 | ❌ 否 | 第三方数据链接 |
| ProductLinkService | 集成 | ✅ 是 | ✅ 是 | 产品集成 |
| 品牌建议服务 | 发现 | ✅ 是 | ✅ 是 | 品牌建议 |
概要统计
- 已实施的服务总数：120个Google Ads API v20服务中的89个
- 测试服务：72（81%的测试覆盖率）
- 核心服务覆盖范围：100%（所有基本服务均已实施）
- 高级功能覆盖：高（已实现最先进的功能）
实施要点
此MCP服务器提供对Google Ads API v20的全面覆盖：
- ✅ 完整的核心服务：所有基本的活动管理服务
- ✅ 高级功能：批量操作、离线转换和数据导入
- ✅ 账户管理：完全计费、用户访问和帐户链接支持
- ✅ 分析与洞察：受众洞察、推荐和搜索功能
- ✅ 类型安全：所有服务都使用proto-plus消息序列化来获得可靠的响应
主要特点
- Proto Plus序列化：所有突变反应均使用
serialize_proto_message用于一致的、类型安全的响应 - 延迟客户端初始化：服务仅在需要时初始化客户端以获得更好的性能
- 全面的错误处理：来自Google Ads API异常的详细错误消息
- 异步支持：所有操作都是异步的，首先使用FastMCP
- 类型注解：已通过版权验证的完整类型覆盖范围（0个错误）
尚未实施的重要服务
虽然此MCP服务器具有出色的覆盖范围，但一些Google Ads API v20服务尚未实现：
- 智能活动设置服务 & SmartCampaign建议服务：高级智能活动功能
- 推荐订阅服务：自动推荐订阅
- FeedService & FeedItem服务：购物订阅源管理
- 扩展FeedItem服务：广告扩展管理
- 活动模拟服务：战役性能模拟
- 本地服务领导服务：当地服务领导管理
- TravelAssets建议服务：旅行特定资产建议
测试
# Run tests
uv run pytest
# Run type checking
uv run pyright
# Run code formatting
uv run ruff format .
贡献
欢迎投稿！请确保：
- 所有代码都有正确的类型注释
- 为新功能添加了测试
- 代码传递
uv run pyright没有错误 - 代码格式为
uv run ruff format
许可证
麻省理工学院
免责声明
这是一个非官方的实现，与谷歌无关、不受谷歌认可或支持。
