内容
# Google Ads MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 LLM（Claude, Copilot, …）提供**只读**访问 Google Ads 账户数据的权限 –
广告活动、广告组、关键词、搜索词、细分性能报告、出价、预算、转化、Performance Max 资产、标签、更改历史、
印象份额，以及一个 ad-hoc GAQL 逃生通道。
它是对 Google Ads 的 GAQL `search_stream` API 的一个薄封装。每个工具都接受每个请求的 `customer_id`，因此一个运行中的服务器可以查询任何经过身份验证的凭证可以访问的账户。
## 两种运行方式
| | 本地（stdio） | 远程（HTTP + OAuth） |
|---|---|---|
| **适用对象** | 个人在其自己的机器上 | 共享一个托管实例的团队 |
| **Google Ads 身份验证** | 您自己的刷新令牌凭证 | 每个用户使用**他们自己的** Google 账户登录；他们的令牌被转发到 Ads API，因此他们只能看到他们个人可以访问的账户 |
| **服务器持有** | 您的完整凭证 | 仅开发者令牌（无 OAuth 机密） |
| **客户端** | Claude Desktop，VS Code/Copilot，任何 stdio MCP 客户端 | Claude.ai 网页连接器，Claude Desktop/Code |
| **设置** | 本 README，下文 | [docs/REMOTE_DEPLOY.md](docs/REMOTE_DEPLOY.md) |
大多数人想要 **本地**。从这里开始。
## 功能
**只读工具**，分组：
- **账户** – 账户发现、元数据、转化操作、标签
- **报告** – 广告活动、广告组、关键词、搜索词、地理 / 设备 / 人口细分、Performance Max 资产
- **诊断** – 质量评分、广告扩展、出价策略、预算调整、更改历史、否定关键词、印象份额
- **查询** – 原始 GAQL `SELECT` + 结构化 GAQL 生成器
- **元数据** – 可选 / 可过滤 / 可排序的字段，每个 GAQL 资源
完整目录及每个工具的描述： **[docs/TOOLS.md](docs/TOOLS.md)**。
---
## 先决条件
- [**uv**](https://docs.astral.sh/uv/getting-started/installation/) – Python 包 / 运行时管理器。
- 一个 **Google Cloud 项目**，启用了 [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com)。
- 一个 **Google Ads 开发者令牌** ([如何获取](https://developers.google.com/google-ads/api/docs/get-started/dev-token))。
- 该项目中的一个 **OAuth 2.0 客户端**（桌面或网页类型）– 用于生成您的刷新令牌。
---
## 本地设置（stdio）
### 1. 克隆和安装
```bash
git clone https://github.com/VidenGrowth/public-google-ads-mcp google-ads-mcp
cd google-ads-mcp
uv sync
```
### 2. 配置凭证
```bash
cp .env.example .env
# 编辑 .env（例如 `nano .env`）并填写您的凭证
```
填写（参见 [.env.example](.env.example) 获取完整列表）：
- `GOOGLE_ADS_DEVELOPER_TOKEN`
- `GOOGLE_ADS_CLIENT_ID`，`GOOGLE_ADS_CLIENT_SECRET`
- `GOOGLE_ADS_REFRESH_TOKEN` *(在此步骤中生成)*
- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` *(可选 – 仅在通过管理器/MCC 账户操作时；数字，无破折线)*
目标 `customer_id` **不** 在 `.env` 中；代理商按每个请求传递它。
### 3. 生成刷新令牌
```bash
uv run auth/generate_refresh_token.py -c client_secret.json
```
使用可以访问您想要的广告账户的 Google 账户登录，然后
将打印的令牌粘贴到 `.env` 中作为 `GOOGLE_ADS_REFRESH_TOKEN`。
完整演练： [auth/README.md](auth/README.md)。
### 4. 本地测试
```bash
uv run python scripts/smoke_test.py
```
预期输出： `✓ 服务器已连接 – 41 个工具已注册`，接着 `get_accessible_accounts`
返回您的账户。如果凭证丢失，您将得到一个明确的
`<error>{"error":"Google Ads 客户端未配置。 …"}</error>` – 修复 `.env`
并重新运行。
随时可以运行测试套件：
```bash
uv run --with pytest pytest tests/ -q
```
### 5. 连接客户端
**Claude Desktop** (`claude_desktop_config.json` – macOS: `~/Library/Application Support/Claude/`，Windows: `%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"google-ads": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/google-ads-mcp", "run", "google-ads-mcp"]
}
}
}
```
完全重启 Claude Desktop（从托盘/菜单退出，而不仅仅是关闭窗口）。
然后在设置中启用 `聊天 > MCP`，从命令运行 **`MCP: 启动服务器`**。
---
## 示例提示
连接后，尝试（替换 ID 为您的一个账户）：
- *"显示客户 1234567890 的所有广告活动"*
- *"查找客户 1234567890 的搜索词中浪费的支出"*
- *"哪些关键词的客户 1234567890 的质量评分低于 5？"*
- *"比较客户 1234567890 在过去 30 天的设备和地理性能"*
- *"显示客户 1234567890 的年龄 + 性别细分"*
- *"客户 1234567890 是否有望在本月花费其预算？"*
参数约定（日期范围、ID/名称过滤器、状态过滤器、排序）已在 [docs/TOOLS_DESIGN.md](docs/TOOLS_DESIGN.md) 中记录。
---
## 远程部署
托管共享实例，每个队友使用他们自己的 Google 账户登录 – 无需每个用户安装，并且每个人只能看到他们可以访问的广告账户 – 使用 Google OAuth 部署 HTTP 传输。
服务器是一个纯粹的 OAuth 资源服务器：MCP 客户端使用 Google 登录，服务器验证每个请求的令牌并将其转发到 Ads API。它仅持有开发者令牌 – 无 OAuth 客户端秘密。
完整指南： **[docs/REMOTE_DEPLOY.md](docs/REMOTE_DEPLOY.md)**。
---
## 身份验证工作原理
- **本地（stdio）：** 服务器使用 *您的* 刷新令牌凭证。没有
MCP 层身份验证 – 服务器在您的机器上运行，在您的控制之下。
- **远程（HTTP）：** 服务器是一个 OAuth 2.0 资源服务器（RFC 9728）。MCP
客户端直接获取 Google 令牌（Google 自己的 OAuth 流），服务器验证每个请求的令牌 –
检查 `aud` 声明和 `adwords` 范围 – 然后将其转发到 Google Ads API。授权是
该用户的 Google 账户可以做的任何事情。服务器不运行任何 OAuth 流并且
存储 **没有** 机密，除了操作员的开发者令牌；OAuth 客户端
机密存在于连接器配置中，不在服务器上。
---
## 架构
参见 [docs/PROJECT_MAP.md](docs/PROJECT_MAP.md) 获取目录游览和请求
流程，以及 [docs/TOOLS_DESIGN.md](docs/TOOLS_DESIGN.md) 获取每个工具遵循的设计约定。
## 许可证
[MIT](LICENSE)。
