AI导哈

广告数据分析服务器

Google Ads MCP Server是一个提供Google Ads API访问的模型上下文协议服务器，用于全面的广告活动分析，支持与Claude Code集成进行对话式广告性能分析。

  • by jgdeutsch
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 jgdeutsch/google-ads-mcp

使用说明

谷歌广告MCP服务器

一个模型上下文协议（MCP）服务器，提供对谷歌广告API的访问，以进行全面的广告活动分析。与Claude Code一起使用，进行对话式广告性能分析。

特性

  • Google OAuth身份验证：使用谷歌安全登录，实现多用户访问
  • 远程HTTP访问：用于远程MCP连接的流式HTTP传输
  • 11分析工具：全面的谷歌广告性能分析
    • 账户信息
    • 活动、广告组和广告绩效指标
    • 关键字性能与质量分数
    • 搜索词报告
    • 性能最大资产组分析
    • 转换动作跟踪
    • 人口统计表现（年龄、性别、设备）
    • 预算节奏和利用率分析
    • 多级数据导出
  • Docker支持：带有健康检查的容器化部署
  • 生产就绪：基于环境的配置、安全最佳实践

先决条件

  • Node.js 24+（或Docker）
  • Google Ads API访问(申请开发者代币)
  • 使用OAuth 2.0凭据的Google Cloud项目
  • 带有活动广告的Google Ads帐户

快速设置（本地开发）

1.克隆和安装

git clone https://github.com/jgdeutsch/google-ads-mcp.git
cd google-ads-mcp
npm install

2.获取Google Ads API证书

  1. 在以下位置创建Google Cloud项目 console.cloud.google.com
  2. 启用Google Ads API
  3. 创建OAuth 2.0凭据（桌面应用程序类型）
  4. 从以下位置获取您的开发人员令牌 谷歌广告API中心

3.获取刷新令牌

# Edit scripts/get_refresh_token.py with your CLIENT_ID and CLIENT_SECRET
python3 scripts/get_refresh_token.py

4.配置环境

cp .env.example .env

# Edit .env and add:
# - GOOGLE_ADS_CLIENT_ID (from OAuth credentials)
# - GOOGLE_ADS_CLIENT_SECRET (from OAuth credentials)
# - GOOGLE_ADS_REFRESH_TOKEN (from step 3)
# - GOOGLE_ADS_DEVELOPER_TOKEN (from API Center)
# - GOOGLE_ADS_LOGIN_CUSTOMER_ID (MCC account, no dashes)
# - GOOGLE_ADS_CUSTOMER_ID (ad account, no dashes)
# - SESSION_SECRET (generate with: openssl rand -base64 32)
# - REQUIRE_AUTH=false (for local use)

5.启动服务器

npm run build && npm start
# Or for development with hot reload:
npm run dev

6.配置克劳德代码

添加 ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

7.克劳德代码测试

You: "Show me campaign performance for last 7 days"
You: "What are my top performing keywords?"
You: "Show search terms with highest spend"
You: "How's my budget pacing this month?"

可用工具

# 工具 说明
1 get-account 账户信息（姓名、货币、时区、状态）
2 get-campaign-performance 带有预算和投标策略的活动指标
3 get-ad-group-performance 广告组指标与活动背景
4 get-ad-performance 个人广告绩效指标
5 get-keyword-performance 带有质量分数的关键字指标
6 get-search-terms 触发广告的搜索查询
7 get-asset-group-performance 性能最大资产组指标
8 get-conversions 转换操作和转换指标
9 get-demographic-performance 按年龄、性别或设备分列的性能
10 get-budget-analysis 预算节奏和利用率
11 export-data 具有每日细分的多级数据导出

日期范围

所有工具都支持这些日期范围预设：

  • TODAY, YESTERDAY
  • LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS
  • THIS_MONTH, LAST_MONTH

Docker部署

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

生产部署（铁路）

  1. 分叉此回购
  2. 连接到铁路
  3. 在铁路仪表板中设置环境变量
  4. 部署（自动使用Dockerfile）

环境变量

看 .env.example 获取完整文档。

必需

变量 描述
GOOGLE_ADS_CLIENT_ID OAuth客户端ID
GOOGLE_ADS_CLIENT_SECRET OAuth客户端密钥
GOOGLE_ADS_REFRESH_TOKEN OAuth刷新令牌
GOOGLE_ADS_DEVELOPER_TOKEN Google Ads API开发者代币
GOOGLE_ADS_LOGIN_CUSTOMER_ID MCC帐户ID（无破折号）
GOOGLE_ADS_CUSTOMER_ID 广告帐户ID（无破折号）
SESSION_SECRET 随机32+字符秘密

可选的

变量 默认值 描述
PORT 3000 服务器端口
HOST 0.0.0.0 绑定地址
NODE_ENV development 环境
REQUIRE_AUTH false 为团队访问启用OAuth
SESSION_TTL 86400000 会话持续时间（ms）

发展

npm install          # Install dependencies
npm run type-check   # Type checking
npm run dev          # Development with hot reload
npm run build        # Build TypeScript
npm start            # Run built version

安全

  • OAuth 2.0与PKCE用于身份验证
  • 24小时到期的不记名代币
  • 非根Docker容器
  • 版本控制中没有秘密
  • .env 排除通过 .gitignore

许可证

麻省理工学院

支持

使用模型上下文协议SDK构建

相关 MCP