内容
<div align="center">
# Google 广告管理协议服务器
**由 Claude 提供全方位读写 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于主动 Google 广告管理。**
由 [**Akela**](https://github.com/akelaonline) 构建
[](LICENSE)
[](pyproject.toml)
[](https://developers.google.com/google-ads/api)
[](tests/)
[](CHANGELOG.md)
[快速开始](#快速开始) · [功能介绍](#功能介绍) · [安全模型](#安全模型) · [文档](#文档) · [更新日志](CHANGELOG.md) · [常见问题](docs/FAQ.md)
</div>
---
## 为什么存在
目前 GitHub 上大多数 Google 广告管理协议服务器仅限于报告功能：`search`、`list_accounts`、原始 GAQL。这些对于分析非常有用，但并不足以满足实际账户管理的需求——暂停消耗预算的广告组、发布新的响应式搜索广告、添加本周搜索词报告中的否定关键词，或者在强劲的一周后调整预算。
本服务器填补了这一空白。它基于 Google 官方的 **`google-ads` Python 客户端**（API v20），封装了大约 40 种工具，涵盖了整个广告活动生命周期，并添加了**人工干预安全层**，确保 LLM 永远不会在未经明确确认的情况下直接修改真实客户的支出——每次写入都会被提议、预览，只有在明确确认后才会执行。
## 功能介绍
| 领域 | 功能 |
|---|---|
| **账户** | 列出可访问的客户、遍历 MCC 层次结构、拉取账户摘要 |
| **报告** | 广告活动 / 广告组 / 关键词 / 广告 / 搜索词表现、变更历史记录、开放式 GAQL |
| **广告活动** | 创建、重命名、暂停/启用、删除 — 任意渠道类型 |
| **预算** | 创建和调整每日预算 |
| **出价** | 手动 CPC、最大转化、目标 CPA、目标 ROAS |
| **广告组** | 创建、暂停/启用、调整 CPC 出价 |
| **广告** | 创建响应式搜索广告、暂停/启用/删除 |
| **关键词** | 添加（带有匹配类型 + 出价）、暂停/启用/删除、广告组或广告活动层面的否定关键词 |
| **受众** | 列出和将用户列表附加到广告组，并带有出价调整 |
| **转化** | 列出转化动作、上传线下转化（为 CRM/WhatsApp 驱动的漏斗而构建） |
完整参数级别参考：[`docs/TOOLS.md`](docs/TOOLS.md)。
## 安全模型
```mermaid
flowchart LR
A[Claude 提议更改] --> B{自动批准？}
B -- 否，默认 --> C[预览 + pending_action_id\n返回，未更改]
C --> D[确认待处理操作]
D --> E[Google Ads API]
B -- 是，启用 --> E
E --> F[(SQLite 审计日志)]
```
每个写入工具（任何名为 `create_*`、`update_*`、`remove_*`、`set_*`、`add_*`、`upload_*` 的工具）都会提议更改而不是直接执行。在调用 `confirm_pending_action(action_id)` 之前，不会对实时账户进行任何操作。提议默认情况下会在 30 分钟后过期。每次执行的变更都会记录到本地 SQLite 审计跟踪中，包含完整的变更前后有效载荷。
完整说明：[`docs/SAFETY.md`](docs/SAFETY.md)。
## 快速开始
```bash
git clone https://github.com/akelaonline/MCP-Google-Ads.git
cd MCP-Google-Ads
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env # 填写凭证 — 参见 docs/SETUP.md
```
**在执行任何操作之前，请先验证安装**（这可以避免因虚拟环境不完整或损坏而导致的调试问题）：
```bash
.venv/bin/python -c "import google_ads_mcp; print('OK:', google_ads_mcp.__file__)"
```
如果未打印 `OK: ...` ，请不要尝试修复 — 删除并重建虚拟环境，这样比调试半安装的虚拟环境更快：
```bash
rm -rf .venv
python -m venv .venv
.venv/bin/python -m pip install -e .
```
> **将 MCP 配置指向虚拟环境的 Python（绝对路径），而不是裸 `python` 。** Claude Desktop 使用其自己的 `PATH` 启动服务器，这可能无法解析到您刚刚创建的虚拟环境 — 这是服务器在手动运行时正常但在 Claude 中显示为“失败”的最常见原因。如果您仍然遇到问题，请参见 [虚拟环境故障排除](docs/SETUP.md#troubleshooting) — 它涵盖了一个特定的损坏模式（重复的 `.venv` 文件，带有 `" 2"` 后缀，来自 macOS Finder 文件夹合并），这会导致 `ModuleNotFoundError` 间歇性出现。
在 Claude Desktop / Claude Code 中注册（`~/.claude/settings.json` 或 `claude_desktop_config.json`）— 将 `command` 指向虚拟环境的 Python，而不是裸 `python`：
```json
{
"mcpServers": {
"google-ads": {
"command": "/绝对路径/到/MCP-Google-Ads/.venv/bin/python",
"args": ["-m", "google_ads_mcp.server"],
"env": { "GOOGLE_ADS_MCP_ENV_FILE": "/绝对路径/到/.env" }
}
}
}
```
重启 Claude 并尝试：**列出我的可访问的 Google Ads 客户 ID 。**
需要开发者令牌 / OAuth 客户端 / 刷新令牌？完整指南参见 [`docs/SETUP.md`](docs/SETUP.md)。如果出现问题？请先查看 [`docs/SETUP.md#troubleshooting`](docs/SETUP.md#troubleshooting) — 大多数安装问题都已在那里诊断。最近的更改请参见 [`CHANGELOG.md`](CHANGELOG.md)。
## 示例
```
> 拉取客户 123-456-7890 的搜索词报告，过去 7 天。
任何花费超过 20 美元且无转化的，添加为否定关键词。
Claude → get_search_terms_report(...)
→ add_negative_keywords(...)
← "提议：向广告活动 111222333 添加 4 个否定关键词：
[广泛匹配] 免费，[广泛匹配] 工作，[广泛匹配] diy，[广泛匹配] 模板
pending_action_id: 7f3a2c1e — 尚未更改。"
> 确认
Claude → confirm_pending_action("7f3a2c1e")
← "完成。已添加 4 个否定关键词。记录到 audit.db。"
```
更多流程和现成的 GAQL 查询：[`docs/EXAMPLES.md`](docs/EXAMPLES.md)。
## 文档
| 文档 | 涵盖内容 |
|---|---|
| [`CHANGELOG.md`](CHANGELOG.md) | 每个版本更改的内容 — 在报告错误之前，请在此处查看 |
| [`docs/SETUP.md`](docs/SETUP.md) | 云项目、OAuth 客户端、开发者令牌、刷新令牌、烟雾测试、故障排除表 |
| [`docs/TOOLS.md`](docs/TOOLS.md) | 每个工具、其参数和返回值 |
| [`docs/SAFETY.md`](docs/SAFETY.md) | 提议/确认和审计日志的工作原理及原因 |
| [`docs/EXAMPLES.md`](docs/EXAMPLES.md) | 示例对话和有用的原始 GAQL 查询 |
| [`docs/FAQ.md`](docs/FAQ.md) | 40 个真实问题 — 从“如何获取令牌”到“为什么不使用现有服务器” |
## 比较
| | 读取报告 | 编写/管理 | 人工干预 | 审计日志 | 自托管，无第三方 |
|---|:---:|:---:|:---:|:---:|:---:|
| **本项目** | ✅ | ✅ | ✅ | ✅ | ✅ |
| 官方 `googleads/google-ads-mcp` | ✅ | ❌ | — | — | ✅ |
| 大多数社区服务器 | ✅ | 部分 | ❌ | ❌ | ✅ |
| 托管/付费聚合器 | ✅ | 视情况而定 | ❌ | ❌ | ❌ |
## 要求
- Python 3.11+
- Google Ads **开发者令牌**，生产环境中使用标准访问权限（[在此处申请](https://developers.google.com/google-ads/api/docs/get-started/dev-token) — 测试访问权限适用于针对测试账户的构建/测试）
- OAuth 2.0 凭证（桌面应用程序）— 参见 [`docs/SETUP.md`](docs/SETUP.md)
## 贡献
欢迎贡献 — 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。有一条硬性规则：每个写入工具都必须经过安全层（`ctx.safety.propose(...)`），而不能直接调用 mutate。
## 许可证
MIT © 2026 [Akela](https://github.com/akelaonline)。参见 [LICENSE](LICENSE)。
如果这为您节省了时间，请在存储库上点赞。
