谷歌广告MCP服务器

Name: 谷歌广告MCP服务器
Author: bjorndavidhansen

作者：bjorndavidhansen15 星标更新：2025-04-18

安装使用来源：spider==github.com

项目介绍

Google Ads MCP 服务器

更新于2025年5月22日 - 自动化洞察功能实现完成

这是一个通过Claude Desktop提供访问Google Ads数据的模型上下文协议（MCP）服务器。

功能

通过Claude访问Google Ads广告系列、账户和绩效指标
预算管理API端点及可视化（量子脉冲项目第三阶段）
关键词管理API端点及可视化（量子脉冲项目第二阶段）
广告组管理API端点（量子脉冲项目第一阶段）
支持经理（MCC）账户和客户账户的数据
内置缓存以提高性能并减少API调用
与Claude Artifacts集成进行数据可视化
多环境支持（开发、测试、生产）
使用Docker容器化部署

量子脉冲项目路线图

本仓库实现了量子脉冲项目的路线图，以增强Google Ads管理能力：

第一阶段：广告组管理API端点（已完成） - 2025年3月29日至4月4日

获取具有过滤功能的广告组
查看广告组绩效指标
创建新的广告组
更新现有广告组
可视化广告组绩效

第二阶段：关键词管理API端点（已完成） - 2025年4月5日至4月18日

浏览具有过滤功能的关键词 ✅
分析搜索词并发现见解 ✅
添加、更新和删除关键词 ✅
通过表格、图表和词云可视化关键词绩效 ✅

第三阶段：预算管理API端点（已完成） - 2025年4月19日至5月2日

获取带有绩效指标的广告系列预算 ✅
分析预算使用情况和分配情况 ✅
生成预算建议 ✅
通过图表和表格可视化预算绩效 ✅
更新预算属性（API调用实现待定）

第四阶段：增强的可视化模板（已完成） - 2025年5月3日至5月16日

实现全面的仪表板模板 ✅
创建比较可视化模板 ✅
构建分解可视化模板 ✅
集成、测试和文档 ✅

第五阶段：自动化洞察功能（已完成） - 2025年5月17日至5月30日

实现性能异常检测 ✅
生成优化建议 ✅
发现增长机会 ✅
创建集成洞察仪表板 ✅

先决条件

Python 3.9或更高版本
Google Ads API凭证
Claude Desktop

快速开始

本地开发

克隆此仓库：

git clone https://github.com/yourusername/google-ads-mcp.git
cd google-ads-mcp

设置虚拟环境：

python -m venv .venv
source .venv/bin/activate  # 在Windows上使用：.venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

创建一个包含您的Google Ads凭证的.env文件：

cp .env.example .env
# 编辑.env文件，添加您的凭证

运行服务器：
```
python server.py
```

Docker部署

构建Docker镜像：

docker build -t google-ads-mcp:latest .

运行容器：

docker run -p 8000:8000 --env-file .env google-ads-mcp:latest

或者使用docker-compose：

docker-compose up -d

配置

应用程序支持不同环境（开发、测试、生产），并具有特定环境的配置：

设置APP_ENV为dev、test或prod以指定环境
根据.env.example中的文档配置环境变量
特性标志允许启用/禁用特定功能

Claude Desktop集成

在Claude Desktop应用配置中设置MCP服务器：

{
    "mcpServers": {
        "google-ads": {
            "command": "python",
            "args": [
                "/绝对路径到server.py"
            ]
        }
    }
}

重启Claude Desktop，并查找工具图标出现
在Claude中使用Google Ads数据，例如询问：
- "显示我的Google Ads账户绩效"
- "在我的账户中哪些广告系列表现良好？"
- "创建我广告系列绩效的可视化"
- "列出123-456-7890账户中的所有广告组"
- "将广告组12345678的状态更新为暂停"
- "在广告系列98765432中创建名为'Summer Products 2025'的新广告组"

广告组管理工具

以下MCP工具可用于广告组管理：

工具	描述
`get_ad_groups`	获取Google Ads账户的广告组，可选过滤
`get_ad_groups_json`	获取用于可视化的JSON格式广告组
`get_ad_group_performance`	获取特定广告组的绩效指标
`get_ad_group_performance_json`	获取用于可视化的JSON格式广告组绩效指标
`create_ad_group`	在广告系列内创建新广告组
`update_ad_group`	更新现有广告组的属性

关键词管理工具

以下MCP工具可用于关键词管理：

工具	描述
`get_keywords`	获取Google Ads账户的关键词，可选过滤
`get_keywords_json`	获取用于可视化的JSON格式关键词
`add_keywords`	向广告组添加新关键词
`update_keyword`	更新现有关键词的状态或出价
`remove_keywords`	从广告组中移除关键词
`get_search_terms_report`	查看触发您广告的搜索词
`get_search_terms_report_json`	获取用于可视化的JSON格式搜索词报告
`analyze_search_terms`	获取关于搜索词绩效的见解
`analyze_search_terms_json`	获取关于搜索词绩效的JSON格式见解

Claude中的示例用法：

"列出123-456-7890账户中的所有关键词"
"显示广告系列12345678的搜索词"
"向广告组87654321添加广泛匹配关键词'夏季鞋'"
"暂停关键词12345"
"分析我的账户中的搜索词以发现机会"

预算管理工具

以下MCP工具可用于预算管理：

工具	描述
`get_budgets`	获取带有绩效指标和利用率的广告系列预算
`get_budgets_json`	获取带有可视化的JSON格式预算信息
`analyze_budgets`	分析预算绩效，提供见解和建议
`update_budget`	更新预算金额或投放方式（占位符实现）

Claude中的示例用法：

"显示我账户中的所有广告系列预算"
"分析我广告系列的预算使用情况"
"按广告系列可视化预算分布"
"哪些预算消耗得太快？"
"我的账户有哪些预算建议？"
"将广告系列12345678的每日预算更新为100美元"

get_budgets示例响应：

预算报告（找到3个预算）

ID: 123456789
名称: 搜索广告系列预算
金额: 50.00美元（每日）
状态: 启用
利用率: 65.4%
关联广告系列: 品牌搜索、通用搜索

ID: 987654321
名称: 展示广告系列预算
金额: 100.00美元（每日）
状态: 启用
利用率: 94.2%
关联广告系列: 再营销展示、探索展示

ID: 456789123
名称: 购物广告系列预算
金额: 75.00美元（每日）
状态: 启用
利用率: 32.1%
关联广告系列: 产品购物

analyze_budgets示例响应：

预算分析报告

预算: 展示广告系列预算（ID: 987654321）
金额: 100.00美元（每日）
利用率: 94.2%
关联广告系列: 再营销展示、探索展示
见解:
- 高利用率（94.2%）
- 预算几乎在一天结束前耗尽
建议:
- 考虑将预算增加至120.00美元
- 或在高峰时段减少竞价调整

预算: 搜索广告系列预算（ID: 123456789）
金额: 50.00美元（每日）
利用率: 65.4%
关联广告系列: 品牌搜索、通用搜索
见解:
- 中等利用率（65.4%）
- 在预算限制内表现良好
建议:
- 监控绩效
- 考虑将预算重新分配给高绩效广告系列

预算: 购物广告系列预算（ID: 456789123）
金额: 75.00美元（每日）
利用率: 32.1%
关联广告系列: 产品购物
见解:
- 低利用率（32.1%）
- 预算持续未充分利用
建议:
- 考虑将预算减少至50.00美元
- 或将预算重新分配给高绩效广告系列

增强的可视化工具

以下MCP工具提供了丰富的数据可视化和高级分析能力：

仪表板可视化工具

工具	描述
`get_account_dashboard_json`	获取包含KPI、趋势和顶级表现者的综合账户仪表板
`get_campaign_dashboard_json`	获取特定广告系列的详细仪表板

Claude中的示例用法：

"显示过去30天的账户仪表板"
"为广告系列12345678创建仪表板"
"比较我账户与上个月的表现"
"显示包含我所有广告系列KPI的仪表板"

账户仪表板包括：

带有同期比较的KPI卡片
关键指标的绩效趋势图表
按绩效排名的顶级广告系列和广告组
成本分布可视化

广告系列仪表板包括：

广告系列概述和详细信息
带有同期比较的KPI卡片
绩效趋势图表
广告组细分
设备性能分布
顶级关键词

比较可视化工具

工具	描述
`get_performance_comparison_json`	比较多个实体（广告系列、广告组）之间的指标

Claude中的示例用法：

"比较广告系列123456和789012"
"显示我前三大广告系列的并排比较"
"跨搜索广告系列比较点击量和转化率"
"哪个广告系列表现更好，123456还是789012？"

比较可视化包括：

关键指标的并排条形图
包含绝对和相对差异的详细比较表
当选择三个或更多指标时的雷达图

分解可视化工具

工具	描述
`get_performance_breakdown_json`	按各种维度（设备、地理位置、时间等）分解绩效

Claude中的示例用法：

"按设备分解广告系列123456的绩效"
"显示我账户按周的绩效"
"我的广告支出的地理分布是什么？"
"按设备和时间分解广告系列123456"

分解可视化包括：

类别维度（设备、网络、地理位置）的堆叠条形图
时间维度（天、周、月）的折线图
层次数据可视化的树状图
包含分段指标和百分比贡献的详细表格

get_account_dashboard_json示例响应：

{
  "date_range": "过去30天",
  "comparison_range": "前30天",
  "visualization": {
    "charts": [
      {
        "type": "折线图",
        "标题": "成本趋势",
        "数据": { ... }
      },
      {
        "type": "折线图",
        "标题": "互动趋势",
        "数据": { ... }
      },
      {
        "type": "环形图",
        "标题": "按广告系列的成本分布",
        "数据": { ... }
      }
    ],
    "tables": [
      {
        "标题": "账户绩效",
        "类型": "KPI卡片",
        "卡片": [ ... ]
      },
      {
        "标题": "按支出排名的顶级广告系列",
        "表头": ["广告系列", "预算", "状态", "成本"],
        "行": [ ... ]
      }
    ]
  }
}

自动化洞察工具

以下MCP工具基于账户数据分析提供自动化的洞察和建议：

异常检测工具

工具	描述
`get_performance_anomalies`	检测广告系列、广告组或关键词的关键绩效指标的重大变化
`get_performance_anomalies_json`	获取带有可视化的JSON格式性能异常数据

Claude中的示例用法：

"查找我账户在过去7天内的性能异常"
"检测我广告系列性能的不寻常变化"
"与上周相比哪些指标有重大变化？"
"分析我账户的性能问题"

性能异常检测包括：

统计分析以识别关键指标中的异常值
与先前时期的比较
检测到的异常的严重程度评分
按指标和实体的异常可视化
最显著变化的排序列表

优化建议工具

工具	描述
`get_optimization_suggestions`	为账户生成可操作的优化建议
`get_optimization_suggestions_json`	获取带有可视化的JSON格式优化建议

Claude中的示例用法：

"我应该对我的账户做出哪些优化？"
"提出改善我广告系列绩效的方法"
"给我一些关键词优化的想法"
"如何更好地分配我的预算？"

优化建议包括：

竞价管理建议（增加/减少竞价）
预算分配建议
负面关键词建议
广告文案改进建议
账户结构建议

机会发现工具

工具	描述
`get_opportunities`	在Google Ads账户中发现增长机会
`get_opportunities_json`	获取带有可视化的JSON格式增长机会

Claude中的示例用法：

"在我的账户中发现增长机会"
"我应该添加哪些搜索词作为关键词？"
"我可以扩展广告覆盖范围的地方在哪里？"
"根据搜索词发现新的关键词机会"

机会发现包括：

基于高性能搜索词的关键词扩展建议
对顶级广告组的广告变体推荐
账户结构优化机会
按潜在影响优先排序的操作列表

集成洞察工具

工具	描述
`get_account_insights_json`	获取结合异常、建议和机会的综合账户洞察

Claude中的示例用法：

"给我一个完整的账户分析"
"我的Google Ads广告系列的整体健康状况如何？"
"显示我应该知道的所有关于账户的信息"
"生成一份综合洞察报告"

集成洞察仪表板包括：

概要统计和主要发现
异常、建议和机会的标签页
优先级建议
每种洞察类型的交互式可视化

get_performance_anomalies示例响应：

Google Ads性能异常
账户ID: 123-456-7890
实体类型: 广告系列
日期范围: 2025-05-15 至 2025-05-22
比较期: 上一期
检测到的异常总数: 3

实体名称                    指标          当前值      前期值      变化        严重程度
--------------------------------------------------------------------------------------
搜索 - 品牌术语           点击次数         250          180          +38.9%        中等
展示 - 再营销             成本            $452.18      $325.45      +38.9%        中等
购物 - 产品               曝光次数         5,420        8,750        -38.1%        高

get_optimization_suggestions示例响应：

Google Ads优化建议
账户ID: 123-456-7890
日期范围: 2025-04-22 至 2025-05-22
总建议数: 5

预算分配建议 (2)
--------------------------------------------------
高: 提高“搜索 - 通用术语”广告系列的预算，该广告系列因预算限制而受限（当前利用率为98%）
     行动: 考虑将预算增加10-20%，以允许增长

中: “展示 - 认知”广告系列显著低于预算（仅利用了45%）
     行动: 考虑减少预算以提高整体账户效率，或将预算重新分配给表现更好的广告系列

竞价管理建议 (2)
--------------------------------------------------
高: 关键词“夏季鞋销售”具有强大的转化率（8.5%），每转化成本