内容
# MCP Google Ads 服务器
MCP（模型上下文协议）服务器，用于 Google Ads API，具有内置的审查前安全保护措施。已在生产环境中证明支持 MCC（管理器帐户）和 36 个用于活动管理、报告和优化的工具。v1.2.0 新增了 Demand Gen 活动的创建。
## 功能
- **MCC 支持**：与管理器帐户和多个客户端帐户一起使用
- **自动上下文**：根据工作目录检测哪个客户端帐户
- **默认安全**：所有新创建的项目都处于暂停状态
- **审批工作流**：在手动审查后启用项目
- **验证**：在创建广告之前验证以尽早发现错误
- **弹性**：断路器、重试和超时处理（cockatiel）
- **结构化日志记录**：基于 Pino 的日志记录，带有构建指纹
## 安装
### 1. Google Ads API 访问权限
您需要：
- Google Ads **开发者令牌** （在 [Google Ads API 中心](https://developers.google.com/google-ads/api/docs/get-started/dev-token) 申请）
- **OAuth 凭证** （来自 Google Cloud 控制台的客户端 ID 和密钥）
- 您的 MCC 帐户的 **刷新令牌**
#### 获取 OAuth 凭证
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
2. 创建项目或选择现有项目
3. 启用 **Google Ads API**
4. 进入 **凭证** → **创建凭证** → **OAuth 客户端 ID**
5. 选择 **桌面应用程序**
6. 下载 JSON 文件（包含 client_id 和 client_secret）
#### 获取刷新令牌
使用您自己的 OAuth 客户端（上述步骤中的 `client_id` / `client_secret`）并运行捆绑的帮助程序。它运行 Google 的安装应用程序循环回调流程**，并使用 **PKCE（S256）** 打印您的刷新令牌。它从您的主目录中读取内容，但不需要任何共享的 OAuth 密钥文件。
```bash
export GOOGLE_ADS_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_CLIENT_SECRET"
node get-refresh-token.cjs
```
您的浏览器会打开 Google 登录页面；请批准使用拥有广告数据的 Google 帐户。成功后，帮助程序会打印一行到 stdout：
```
GOOGLE_ADS_REFRESH_TOKEN=1//0a...
```
在您的环境（或下面的 `config.json`）中设置该值。请求的 OAuth 范围从 `config.json`（`oauth.scope`）读取，默认为 `config.example.json`，因此帮助程序和运行的服务器始终请求相同的范围。此 MCP 只请求所需的最低范围：`https://www.googleapis.com/auth/adwords`。
> 请勿将 stdout 重定向到共享日志文件 — 刷新令牌按设计打印到 stdout。
注意：`GOOGLE_ADS_DEVELOPER_TOKEN` 是单独的 Google Ads API 凭证，而不是 OAuth 范围 — 请独立设置它（参见下面的环境变量）。
### 2. 安装
```bash
npm install mcp-google-ads
```
或从源代码克隆并构建：
```bash
git clone https://github.com/mharnett/mcp-google-ads.git
cd mcp-google-ads
npm install
npm run build
```
**安全**：请勿共享您的 `.mcp.json` 文件或将其提交到 git — 它可能包含 API 凭证。 将 `.mcp.json` 添加到您的 `.gitignore` 中。
### 3. 配置
```bash
cp config.example.json config.json
```
使用您的凭证编辑 `config.json`:
```json
{
"oauth": {
"scope": "https://www.googleapis.com/auth/adwords"
},
"google_ads": {
"developer_token": "YOUR_DEVELOPER_TOKEN",
"client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN",
"mcc_customer_id": "123-456-7890"
},
"clients": {
"my-client": {
"customer_id": "111-222-3333",
"name": "我的客户端",
"folder": "/path/to/client/workspace"
},
"another-client": {
"customer_id": "444-555-6666",
"name": "另一个客户端",
"folder": "/path/to/another/workspace"
}
},
"defaults": {
"create_paused": true,
"label_prefix": "claude-",
"require_approval_for_enable": true
}
}
```
### 环境变量
或者，通过环境变量设置凭证（这些变量会覆盖 `config.json`）：
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `GOOGLE_ADS_DEVELOPER_TOKEN` | 是 | Google Ads API 开发者令牌 |
| `GOOGLE_ADS_CLIENT_ID` | 是 | OAuth 2.0 客户端 ID |
| `GOOGLE_ADS_CLIENT_SECRET` | 是 | OAuth 2.0 客户端密钥 |
| `GOOGLE_ADS_REFRESH_TOKEN` | 是 | OAuth 2.0 刷新令牌 |
| `GOOGLE_ADS_MCP_WRITE` | 否 | 设置为 `true` 以公开变异工具（创建/更新/暂停/启用/删除/应用）。 默认：只读。 |
### 默认情况下为只读
服务器默认情况下为只读。 变异工具（任何创建、更新、暂停、启用、删除、链接或应用的工具）隐藏在工具列表中，直到您在 MCP 服务器环境中设置 `GOOGLE_ADS_MCP_WRITE=true`。 如果在没有该标志的情况下调用写工具，服务器会返回一个明确的错误，指向环境变量。
这是故意的：诸如“激活筹款活动”之类的随意聊天消息不应在没有明确选择的情况下移动实时广告支出。
### 4. 添加到 Claude Code
将以下内容添加到您的 Claude Code MCP 设置（`~/.claude/settings.json` 或项目设置）：
```json
{
"mcpServers": {
"google-ads": {
"command": "node",
"args": ["node_modules/mcp-google-ads/dist/index.js"]
}
}
}
```
或如果从源代码安装：
```json
{
"mcpServers": {
"google-ads": {
"command": "node",
"args": ["/path/to/mcp-google-ads/dist/index.js"]
}
}
}
```
重启 Claude Code。
**Claude 桌面版：** 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）。
## 用法
### 工作流程
```
1. 进入客户端文件夹 → 自动检测帐户上下文
2. 请求 Claude 创建活动/广告 → 所有创建的活动都处于暂停状态
3. 在 Google Ads UI 或编辑器中审查
4. 告诉 Claude 启用已批准的项目
5. Claude 启用（需要您的批准提示）
```
### 可用工具（36）
#### 上下文和发现
| 工具 | 描述 |
|------|-------------|
| `google_ads_get_client_context` | 从工作目录检测哪个帐户 |
| `google_ads_list_campaigns` | 列出所有活动及其状态和指标 |
| `google_ads_list_ad_groups` | 列出活动中的广告组 |
| `google_ads_list_pending_changes` | 显示带有 claude- 标签的暂停项目 |
| `google_ads_list_conversion_actions` | 列出转化操作 |
#### 活动管理
| 工具 | 描述 |
|------|-------------|
| `google_ads_create_campaign` | 创建活动（暂停）。 支持 SEARCH + DEMAND_GEN 通道，更丰富的出价（MANUAL_CPC / MAXIMIZE_CLICKS / MAXIMIZE_CONVERSIONS / TARGET_CPA），地理和语言定位，开始/结束日期 |
| `google_ads_create_ad_group` | 创建广告组（暂停）。 `type` 接受 SEARCH_STANDARD（默认）或 DEMAND_GEN_MULTI_ASSET_AD_GROUP |
| `google_ads_create_responsive_search_ad` | 创建 RSA 并进行验证（暂停） |
| `google_ads_create_image_asset` | 上传 PNG/JPG/GIF 图片资产（验证 ≤5MB，≥600×314）用于 Demand Gen 广告 |
| `google_ads_create_demand_gen_multi_asset_ad` | 创建 Demand Gen 多资产广告（暂停）- 验证字符/计数上限，然后再进行 API 调用，如果 ad_group 不是 DG，则快速失败 |
| `google_ads_create_keywords` | 创建关键词（暂停） |
| `google_ads_validate_ad` | 在创建之前验证 RSA |
| `google_ads_enable_items` | 启用项目（使其上线）- **需要批准** |
| `google_ads_pause_items` | 暂停活动项目 |
| `google_ads_pause_keywords` | 暂停特定关键词 |
| `google_ads_update_campaign_budget` | 更新活动每日预算 |
#### 跟踪和网址
| 工具 | 描述 |
|------|-------------|
| `google_ads_get_campaign_tracking` | 获取跟踪模板和网址参数 |
| `google_ads_update_campaign_tracking` | 更新跟踪模板 |
#### 否定关键词
| 工具 | 描述 |
|------|-------------|
| `google_ads_create_shared_set` | 创建共享否定关键词列表 |
| `google_ads_link_shared_set` | 将共享集合链接到活动 |
| `google_ads_unlink_shared_set` | 将共享集合从活动取消链接 |
| `google_ads_add_shared_negatives` | 将关键词添加到共享否定列表 |
| `google_ads_remove_shared_negatives` | 从共享列表中删除关键词 |
| `google_ads_add_campaign_negatives` | 添加活动级否定关键词 |
| `google_ads_remove_campaign_negatives` | 删除活动级否定关键词 |
| `google_ads_remove_adgroup_negatives` | 删除广告组级否定关键词 |
#### 性能和报告
| 工具 | 描述 |
|------|-------------|
| `google_ads_keyword_performance` | 关键词指标和质量评分 |
| `google_ads_keyword_performance_by_conversion` | 按转化操作划分的关键词指标 |
| `google_ads_ad_performance` | 广告级别的性能指标 |
| `google_ads_ad_performance_by_conversion` | 按转化操作划分的广告指标 |
| `google_ads_search_term_report` | 搜索词查询报告 |
| `google_ads_search_term_report_by_conversion` | 按转化操作划分的搜索词 |
| `google_ads_search_term_insights` | 搜索词类别洞察 |
| `google_ads_search_term_insight_terms` | 洞察类别中的术语 |
| `google_ads_keyword_volume` | 关键词规划师容量估计 |
#### 高级
| 工具 | 描述 |
|------|-------------|
| `google_ads_gaql_query` | 运行原始 GAQL 查询 |
### 示例命令
```
# 检查您连接的帐户
" 我连接到哪个 Google Ads 帐户？"
# 列出活动
" 显示此帐户中的所有活动"
# 创建新活动
" 创建一个搜索活动，品牌术语每天 50 美元预算"
# 检查待审内容
" 有哪些更改待我审核？"
# 在 Google Ads UI 审查后
" 启用品牌活动中已批准的广告"
# 性能分析
" 显示过去 30 天的关键词性能，按成本排序"
# 运行自定义 GAQL
" 运行 GAQL 查询以获取所有点击率低于 2% 的广告组"
```
### 示例：创建 Demand Gen 活动端到端
```
# 1. 活动：$75/天，DEMAND_GEN 通道，默认 MAXIMIZE_CONVERSIONS，
# 定位阿拉斯加州 (21134) 和 Maine (21141) 的英语
google_ads_create_campaign({
name: "DG - 春季促销",
daily_budget: 75,
channel_type: "DEMAND_GEN",
geo_target_ids: ["21134", "21141"],
start_date: "2026-05-01",
end_date: "2026-06-30"
})
# → campaign_id: 555123
# 2. 广告组：DEMAND_GEN_MULTI_ASSET_AD_GROUP
google_ads_create_ad_group({
campaign_id: "555123",
name: "DG AG 1",
type: "DEMAND_GEN_MULTI_ASSET_AD_GROUP"
})
# → ad_group_id: 555456
# 3. 图片资产（PNG/JPG/GIF，≥600×314，≤5MB）。 返回 {asset_id, ...}
google_ads_create_image_asset({ name: "hero-landscape", file_path: "/abs/path/hero.png" })
# → asset_id: 42001
google_ads_create_image_asset({ name: "hero-square", file_path: "/abs/path/square.png" })
# → asset_id: 42002
google_ads_create_image_asset({ name: "logo", file_path: "/abs/path/logo.png" })
# → asset_id: 42003
# 4. Demand Gen 多资产广告（暂停）。 验证字符 + 计数上限。
google_ads_create_demand_gen_multi_asset_ad({
ad_group_id: "555456",
final_urls: ["https://example.com/spring"],
business_name: "Example Org",
call_to_action: "LEARN_MORE",
marketing_image_asset_ids: ["42001"], # 1.91:1 景观，≥1 个必填
square_marketing_image_asset_ids: ["42002"], # 1:1 可选
logo_image_asset_ids: ["42003"], # logo 可选
headlines: ["春季大促销，现在就买", "今日省 20%"], # 最多 5 个，每个 ≤40 个字符
long_headlines: ["A longer pitch under ninety characters."], # 最多 5 个，≤90 个字符
descriptions: ["购买最新的款式。", "免费退货。"] # 最多 5 个，每个 ≤90 个字符
})
# → resource_name: customers/.../adGroupAds/555456~67890000
```
所有四个调用完成后，活动、广告组和广告都在线上，以 PAUSED 状态存在，并带有 `Claude-MM-DD-YY` 标签。在 Google Ads UI 中审查，然后通过 `google_ads_enable_items` 启用。
## 安全功能
1. **所有内容都从 PAUSED 开始** - 除非您明确启用，否则不会上线
2. **标签跟踪** - 所有 Claude 创建的项目都添加 `claude-pending` 标签
3. **验证** - 创建前验证广告（标题/描述长度等）
4. **批准提示** - `enable_items` 工具需要 Claude Code 中的明确批准
5. **客户端隔离** - 工作目录确定帐户，防止跨客户端错误
## 添加新客户端
编辑 `config.json` 以添加客户端。 将每个客户端映射到一个工作目录：
```json
{
"clients": {
"client-slug": {
"customer_id": "123-456-7890",
"name": "客户端名称",
"folder": "/path/to/client/workspace"
}
}
}
```
无需重启服务器 - 每次请求都读取配置。
## 故障排除
### "未找到工作目录的客户端"
- 确保您位于与其中一个 `clients` 条目匹配的文件夹中
- 检查 `config.json` 中的文件夹路径是否完全匹配
### "开发者令牌未批准"
- 新的开发者令牌需要 Google 的批准
- 在等待批准期间使用测试帐户
### "身份验证失败"
- 刷新令牌可能已过期 - 重新生成它
- 检查 client_id 和 client_secret 是否正确
## 许可证
MIT - 有关详细信息，请参见 [LICENSE](LICENSE)。
