Google Ads MCP Server (google-ads-mcp-server)

谷歌广告MCP服务器

*更新于2025年5月22日-第5阶段自动洞察功能实施完成*

一种模型上下文协议（MCP）服务器，通过Claude Desktop提供对Google广告数据的访问。

特性

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

量子脉冲项目路线图

此存储库实现了Project Quantum Pulse路线图，以增强Google广告管理功能：

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

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

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

• 使用过滤功能浏览关键字✅
• 分析搜索词并找到见解✅
• 添加、更新和删除关键字✅
• 使用表格、图表和单词云可视化关键字性能✅

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

• 使用绩效指标检索活动预算✅
• 分析预算使用和分配✅
• 生成预算建议✅
• 用图表和表格可视化预算执行情况✅
• 更新预算属性（API调用实现挂起）

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

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

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

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

先决条件

• Python 3.9或更高版本
• Google Ads API证书
• 克劳德桌面

快速开始

地方发展

1. 克隆此存储库：

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

1. 设置虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate

1. 安装依赖项：

   pip install -r requirements.txt

1. 创建一个 .env 使用您的Google Ads凭据文件：

   cp .env.example .env
   # Edit .env file with your credentials

1. 运行服务器：

   python server.py

Docker部署

1. 构建Docker镜像：

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

1. 运行容器：

   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桌面集成

1. 在Claude Desktop App配置中为MCP服务器配置Claude Desktop：

   {
       "mcpServers": {
           "google-ads": {
               "command": "python",
               "args": [
                   "/absolute/path/to/server.py"
               ]
           }
       }
   }

1. 重新启动Claude Desktop并查找要显示的工具图标

1. 在Claude中使用谷歌广告数据，可以问以下问题：

- “显示我的Google Ads帐户性能” - “我的账户中哪些活动表现良好？” - “创建我的活动绩效可视化” - “列出我123-456-7890帐户中的所有广告组” - “将广告组12345678的状态更新为暂停” - 在活动98765432中创建一个名为“夏季产品2025”的新广告组

广告组管理工具

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

关键字管理工具

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

Claude中的示例用法：

• “列出我123-456-7890帐户中的所有关键字”
• “显示活动12345678的搜索词”
• “在广告组87654321中添加一个广泛匹配的关键字‘夏季鞋’”
• “暂停关键字12345”
• “分析我帐户中的搜索词以寻找机会”

预算管理工具

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

Claude中的示例用法：

• “显示我帐户中的所有活动预算”
• “分析我的活动中的预算利用率”
• “按活动可视化预算分配”
• “哪些预算消耗得太快？”
• “我的账户的预算建议是什么？”
• “将活动12345678的每日预算更新为100美元”

示例响应 get_budgets:

Budget Report (3 budgets found)

ID: 123456789
Name: Search Campaign Budget
Amount: 50.00 USD (Daily)
Status: ENABLED
Utilization: 65.4%
Associated Campaigns: Brand Search, Generic Search

ID: 987654321
Name: Display Campaign Budget
Amount: 100.00 USD (Daily)
Status: ENABLED
Utilization: 94.2%
Associated Campaigns: Retargeting Display, Prospecting Display

ID: 456789123
Name: Shopping Campaign Budget
Amount: 75.00 USD (Daily)
Status: ENABLED
Utilization: 32.1%
Associated Campaigns: Product Shopping

示例响应 analyze_budgets:

Budget Analysis Report

Budget: Display Campaign Budget (ID: 987654321)
Amount: 100.00 USD (Daily)
Utilization: 94.2%
Associated Campaigns: Retargeting Display, Prospecting Display
Insights:
- High Utilization (94.2%)
- Budget nearly depleted before day end
Recommendations:
- Consider increasing budget to 120.00 USD
- Or reduce bid adjustments during peak hours

Budget: Search Campaign Budget (ID: 123456789)
Amount: 50.00 USD (Daily)
Utilization: 65.4%
Associated Campaigns: Brand Search, Generic Search
Insights:
- Moderate Utilization (65.4%)
- Performing well within budget constraints
Recommendations:
- Monitor performance
- Consider reallocating budget to high-performing campaigns

Budget: Shopping Campaign Budget (ID: 456789123)
Amount: 75.00 USD (Daily)
Utilization: 32.1%
Associated Campaigns: Product Shopping
Insights:
- Low Utilization (32.1%)
- Budget consistently underutilized
Recommendations:
- Consider reducing budget to 50.00 USD
- Or reallocate budget to higher-performing campaigns

增强的可视化工具

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

仪表板可视化工具

Claude中的示例用法：

• “显示过去30天的帐户仪表板”
• “为活动12345678创建仪表板”
• “将我的帐户性能与上个月进行比较”
• “显示包含我所有活动KPI的仪表板”

帐户仪表板包括：

• 带有期间比较的KPI卡
• 关键指标的绩效趋势图
• 按表现排名的顶级活动和广告组
• 成本分布可视化

活动控制面板包括：

• 活动概述和详细信息
• 带有期间比较的KPI卡
• 性能趋势图
• 广告组细分
• 设备性能分布
• 热门关键词

比较可视化工具

Claude中的示例用法：

• “比较活动123456和789012”
• “显示我的前3个广告系列的并排比较”
• “比较我的搜索活动中的点击量和转化率”
• “哪个活动的表现更好，123456还是789012？”

比较可视化包括：

• 关键指标的并排条形图
• 具有绝对和相对差异的详细比较表
• 用于多指标比较的雷达图（当选择3+指标时）

故障可视化工具

Claude中的示例用法：

• “按设备细分活动123456性能”
• “按星期显示我的帐户性能”
• “我的广告支出的地理分布是什么？”
• “按设备和时间分解活动123456”

分解可视化包括：

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

示例响应 get_account_dashboard_json:

{
  "date_range": "LAST 30 DAYS",
  "comparison_range": "PREVIOUS 30 DAYS",
  "visualization": {
    "charts": [
      {
        "type": "line",
        "title": "Cost Trend",
        "data": { ... }
      },
      {
        "type": "line",
        "title": "Engagement Trend",
        "data": { ... }
      },
      {
        "type": "doughnut",
        "title": "Cost Distribution by Campaign",
        "data": { ... }
      }
    ],
    "tables": [
      {
        "title": "Account Performance",
        "type": "kpi_cards",
        "cards": [ ... ]
      },
      {
        "title": "Top Campaigns by Spend",
        "headers": ["Campaign", "Budget", "Status", "Cost"],
        "rows": [ ... ]
      }
    ]
  }
}

自动化洞察工具

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

异常检测工具

Claude中的示例用法：

• “在我的帐户中查找过去7天的性能异常”
• “检测我的活动表现中的异常变化”
• “与上周相比，哪些指标有重大变化？”
• “分析我的帐户性能问题”

性能异常检测包括：

• 统计分析以识别关键指标中的异常值
• 与以往期间的比较
• 对检测到的异常进行严重性评分
• 按度量和实体可视化异常
• 最重要变化排名

优化建议工具

Claude中的示例用法：

• “我应该对我的帐户进行哪些优化？”
• “建议提高我的活动绩效的方法”
• “为我的关键字提供优化建议”
• “我怎样才能更好地分配预算？”

优化建议包括：

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

机会发现工具

Claude中的示例用法：

• “在我的客户中寻找增长机会”
• “我应该添加哪些搜索词作为关键字？”
• “我在哪里可以扩大我的广告范围？”
• “根据搜索词发现新的关键字机会”

机会发现包括：

• 基于高性能搜索词的关键字扩展建议
• 针对顶级广告组的广告变体建议
• 账户结构优化机会
• 按潜在影响排序的行动清单

集成洞察工具

Claude中的示例用法：

• “给我一份完整的账户分析”
• “我的谷歌广告活动的整体健康状况如何？”
• “向我展示我应该知道的关于我的帐户的一切”
• “生成一份全面的见解报告”

集成洞察仪表板包括：

• 统计摘要和主要调查结果
• 异常、建议和机会选项卡
• 优先建议
• 每种洞察类型的交互式可视化

示例响应 get_performance_anomalies:

Google Ads Performance Anomalies
Account ID: 123-456-7890
Entity Type: CAMPAIGN
Date Range: 2025-05-15 to 2025-05-22
Comparison Period: PREVIOUS_PERIOD
Total Anomalies Detected: 3

Entity Name                    Metric          Current      Previous     Change        Severity
----------------------------------------------------------------------------------------------
Search - Brand Terms           clicks          250          180          +38.9%        MEDIUM
Display - Retargeting          cost            $452.18      $325.45      +38.9%        MEDIUM
Shopping - Products            impressions     5,420        8,750        -38.1%        HIGH

示例响应 get_optimization_suggestions:

Google Ads Optimization Suggestions
Account ID: 123-456-7890
Date Range: 2025-04-22 to 2025-05-22
Total Suggestions: 5

Budget Allocation Suggestions (2)
--------------------------------------------------
HIGH: Increase budget for campaign 'Search - Generic Terms' which is limited by budget (currently at 98% utilization)
     Action: Consider increasing the budget by 10-20% to allow for growth

MEDIUM: Campaign 'Display - Awareness' is significantly under budget (only 45% utilized)
     Action: Consider decreasing the budget to improve overall account efficiency, or reallocate to better-performing campaigns

Bid Management Suggestions (2)
--------------------------------------------------
HIGH: Keyword 'summer shoes sale' has strong conversion rate (8.5%) at $12.50 per conversion
     Action: Increase bid by 10-15% to capture more traffic for this high-performing keyword

MEDIUM: Keyword 'generic footwear' has high CPC ($2.75) with no conversions after 45 clicks
     Action: Decrease bid by 25-30% or pause if performance doesn't improve

Negative Keywords Suggestions (1)
--------------------------------------------------
MEDIUM: Add 'free shoes' as a negative keyword - spent $45.25 with no conversions
     Action: Add 'free shoes' as a negative exact match keyword to prevent further wasted spend

示例响应 get_opportunities:

Google Ads Growth Opportunities
Account ID: 123-456-7890
Date Range: 2025-04-22 to 2025-05-22
Total Opportunities: 4

Keyword Expansion Opportunities (2)
--------------------------------------------------
HIGH: Add 'summer sandals women' as a keyword in ad group 'Women's Footwear'
     Action: Add 'summer sandals women' as an exact match keyword to better control bidding and relevance

MEDIUM: Add 'designer shoes discount' as a keyword in ad group 'Designer Collection'
     Action: Add 'designer shoes discount' as an exact match keyword to better control bidding and relevance

Ad Variation Opportunities (2)
--------------------------------------------------
MEDIUM: Create additional ad variations for ad group 'Men's Dress Shoes'
     Action: Add at least one more responsive search ad to test different headlines and descriptions

MEDIUM: Create additional ad variations for ad group 'Women's Athletic Shoes'
     Action: Add at least one more responsive search ad to test different headlines and descriptions

部署

此存储库包括用于部署的Kubernetes清单：

• kubernetes/dev/ -开发环境部署
• kubernetes/test/ -测试环境部署
• kubernetes/prod/ -生产环境部署

CI/CD管道是使用GitHub Actions配置的，用于自动化测试、构建和部署。

安全

• 所有凭据都存储在Kubernetes secrets或环境变量中，从不存储在代码中
• 服务器对API访问使用正确的身份验证
• 在生产环境中启用了速率限制
• 遵循容器安全最佳实践

测试

运行测试套件：

pytest

运行特定测试：

# Test Ad Group functionality
python -m google_ads_mcp_server.tests.unit.test_ad_groups

# Test Keyword functionality
python -m google_ads_mcp_server.tests.unit.test_keywords

# Test Budget functionality
python -m google_ads_mcp_server.tests.unit.test_budgets

# Test MCP Tools
python -m google_ads_mcp_server.tests.unit.test_tools

# Test Visualization formatters
python -m google_ads_mcp_server.tests.unit.test_visualizations

# Test Budget Visualizations
python -m google_ads_mcp_server.tests.unit.test_budget_visualizations

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 提交您的更改： git commit -am 'Add new feature'
4. 推到分支： git push origin feature/my-feature
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• Google Ads API团队的文档和支持
• 克劳德的拟人化与模型上下文协议