内容
# AdMob MCP 服务器
[](https://www.npmjs.com/package/admob-mcp-server)
[](https://github.com/ParkSangGwon/admob-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
**中文** | [한국어](README.ko.md)
通过自然语言询问您的 AI 助手关于您的 AdMob 应用和收入的问题：
> - "我的应用在过去 7 天内赚了多少钱，按国家划分？"
> - "哪个媒介广告源本月有最佳的 eCPM？"
> - "比较我的横幅广告和奖励广告单元的 RPM。"
> - "为我的新游戏创建奖励广告单元。"
这是 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的 [Google AdMob API](https://developers.google.com/admob/api) 服务器。
它与 Claude Code、Claude Desktop、Cursor、Gemini CLI 和任何其他支持 MCP 的 AI 客户端配合使用。
## 架构
```mermaid
flowchart LR
C["MCP 客户端<br/>Claude Code · Claude Desktop · Cursor · Gemini CLI"]
subgraph S["admob-mcp-server — 在您的机器上运行"]
direction TB
T["5 个工具集中的 18 种工具<br/>账户 · 应用 · 广告单元 · 报告 · 媒介<br/>(按 --toolsets / --read-only 筛选)"]
A["凭证解析器<br/>环境变量 → token.json → gcloud ADC"]
R["报告扁平化<br/>分段流 → 行 · 微妙 → 货币"]
end
G["Google AdMob API<br/>v1beta"]
C <-->|"MCP 通过 stdio"| T
T --> A
A <-->|"OAuth 2.0 / HTTPS"| G
G -.->|"报告分段"| R
R -.-> T
```
凭证和收入数据仅在您的机器和 Google 之间传输 — 中间没有第三方服务器。
## 功能
- **完整的 AdMob API v1beta 覆盖** — 18 种工具涵盖账户、应用、广告单元、报告和媒介，包括 v1 API 没有的写入操作
- **报告变得可读** — 流式报告响应被扁平化为简单的行表格，货币价值（微妙）被转换为实际货币单位
- **需要时为只读模式** — 通过 `--read-only` 隐藏所有写入工具（创建/更新）并颁发无法修改任何内容的令牌
- **工具集** — 仅启用您需要的工具组，例如 `--toolsets reports,accounts`
- **三种身份验证选项** — 一键式浏览器登录（`npx admob-mcp-server auth`）、环境变量刷新令牌或 gcloud 应用程序默认凭证
- **内置分析提示** 和报告规范参考资源
## 快速设置
一次性设置，大约 10 分钟：
| 步骤 | 您需要做的 | 位置 |
| ------------------------------------------------------------ | ----------------------------------------------------------------- | -------- |
| [1. Google Cloud 设置](#part-1--google-cloud-setup) | 注册一个个人“应用”，以便 Google 允许您访问自己的数据 | 浏览器 |
| [2. 登录](#part-2--sign-in) | 运行一个命令并使用 Google 登录 | 终端 |
| [3. 连接您的 AI 客户端](#part-3--connect-your-ai-client) | 添加一个配置项并重启客户端 | 终端 |
### 要求
- **Node.js 18 或更新版本** — 使用 `node --version` 检查；如果缺少，请从 [nodejs.org](https://nodejs.org) 安装
- 一个 [AdMob](https://admob.google.com) 账户和拥有该账户的 Google 账户
## 设置
### 第 1 部分 — Google Cloud 设置
为什么需要这样做？\
AdMob API 没有简单的 API 密钥 — Google 要求访问您数据的每个程序都必须注册为“OAuth 应用”。
在这里，您注册一个个人应用，只有您会使用。
它是免费的，不需要设置计费。
1. **创建（或选择）一个 Google Cloud 项目**： [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate) — 任何名称都有效；重复使用现有项目也可以。
2. **启用 AdMob API**： [console.cloud.google.com/apis/library/admob.googleapis.com](https://console.cloud.google.com/apis/library/admob.googleapis.com) → 检查顶部栏中是否选择了您的项目 → **启用**。
3. **配置 OAuth 同意屏幕**： [console.cloud.google.com/auth/overview](https://console.cloud.google.com/auth/overview) — 第一次访问会打开一个简短的向导：
- 应用名称：任何内容（例如 `admob-mcp`），您的电子邮件作为支持/联系电子邮件
- 受众：**外部**
- 完成向导 — 您 **不需要** 将应用提交给 Google 验证
- 然后进入 **受众 → 测试用户 → 添加用户** 并添加 **拥有您的 AdMob 账户的 Google 账户**
4. **创建 OAuth 客户端**： [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) → **创建凭证 → OAuth 客户端 ID**
- 应用类型：**桌面应用**
- 创建后，点击 **下载 JSON** — 您将在第 2 部分中使用此文件
> [!WARNING]
> 当同意屏幕处于 **测试** 模式时，Google 会在 **7 天** 后过期登录，因此您需要每周重新运行登录。
> 要停止此操作，请发布应用（**受众 → 发布应用**）。
> 为您自己发布应用不需要 Google 的验证 — 您只会在登录期间看到“未验证的应用”警告，这是预期的。
### 第 2 部分 — 登录
将您下载的 JSON 文件移动到服务器查找的位置，然后运行登录命令：
```bash
mkdir -p ~/.admob-mcp
mv ~/Downloads/client_secret_*.json ~/.admob-mcp/oauth_client.json
npx admob-mcp-server auth
```
（在 Windows 上，在资源管理器中将文件移动到 `C:\Users\<you>\.admob-mcp\oauth_client.json`，然后运行 `npx` 命令。）
您的浏览器会打开。
选择 **拥有您的 AdMob 账户的 Google 账户** 并允许访问。
如果您看到 **“Google 未验证此应用”** 警告，那是您在第 1 部分的应用 — 点击“继续”。
当终端打印 `设置完成` 时，您的登录已保存到 `~/.admob-mcp/token.json` 并从那时起重复使用。
默认情况下，登录涵盖所有工具，包括写入工具。
如果您只想要报告访问权限，请改为运行 `npx admob-mcp-server auth --read-only`。
`auth` 命令的作用：
```mermaid
sequenceDiagram
autonumber
participant T as 终端
participant S as admob-mcp-server
participant B as 浏览器
participant G as Google
T->>S: npx admob-mcp-server auth
S->>S: 读取 ~/.admob-mcp/oauth_client.json
S->>B: 打开同意 URL（循环重定向，随机端口）
B->>G: 登录和允许范围
G-->>S: 授权码 → 刷新令牌
S->>S: 保存 ~/.admob-mcp/token.json（用于后续每次调用）
```
<details>
<summary><b>高级：环境变量（无头/CI）</b></summary>
如果您已经有一个刷新令牌，则不需要文件（写入工具还需要令牌来覆盖 `admob.monetization` 范围）：
```bash
export GOOGLE_CLIENT_ID="....apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="..."
export GOOGLE_REFRESH_TOKEN="..."
```
</details>
<details>
<summary><b>高级：gcloud 应用程序默认凭证</b></summary>
与 Google 官方 Analytics/Ads MCP 服务器使用的模式相同：
```bash
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/admob.readonly,https://www.googleapis.com/auth/admob.report,https://www.googleapis.com/auth/admob.monetization,https://www.googleapis.com/auth/cloud-platform \
--client-id-file=path/to/oauth_client.json
```
如果您只需要报告访问权限，请删除 `admob.monetization` 范围。
</details>
凭证解析顺序：**环境变量 → `token.json`（来自 `auth`）→ ADC**。
### 第 3 部分 — 连接您的 AI 客户端
选择下面的客户端。
MCP 服务器在客户端启动时加载，因此 **在添加配置后重启客户端**。
**Claude Code**
```bash
claude mcp add admob -- npx -y admob-mcp-server
```
通过 `claude mcp list` 验证 — 您应该看到 `admob: ... - ✔ 已连接`。
**Claude Desktop** — 打开 **设置 → 开发者 → 编辑配置**，打开 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`），并添加：
```json
{
"mcpServers": {
"admob": {
"command": "npx",
"args": ["-y", "admob-mcp-server"]
}
}
}
```
重启应用；广告工具出现在聊天输入的工具菜单中。
**Cursor** — 将相同的 `mcpServers` 块添加到 `~/.cursor/mcp.json`，然后检查 **设置 → MCP** 显示 admob 已启用。
**Gemini CLI** — 将相同的 `mcpServers` 块添加到 `~/.gemini/settings.json`，然后通过 CLI 中的 `/mcp` 检查。
> [!TIP]
> 如果您使用了环境变量登录，请通过客户端的 `env` 块传递变量（Claude Code：在 `--` 之前重复 `--env KEY=value`；JSON 配置：在 `"args"` 旁边添加 `"env": { ... }` 对象）。
## 试用
您不需要自己调用工具 — 只需用自然语言询问，助手会选择合适的工具。
一些启动器：
- _“我的应用上周赚了多少钱？”_
- _“按国家和应用划分本月的收入。”_
- _“过去 30 天内，哪种广告格式的 RPM 最高？”_
- _“我的媒介表现如何？按观察到的 eCPM 比较广告源。”_
- _“列出我的应用及其广告单元。”_
- _“为我的游戏应用创建名为 'shop_reward' 的奖励广告单元。”_
大多数客户端在每次工具调用前都会请求您的许可，因此在您批准之前不会运行任何操作（尤其是写入操作）。
## 配置
所有配置都是可选的 — 默认设置适用于单个 AdMob 账户。
### 环境变量
| 变量 | 描述 | 默认值 |
| ------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- |
| `ADMOB_ACCOUNT` | 发布者 ID（`pub-XXXXXXXXXXXXXXXX`）。仅当您的登录可以访问多个账户时需要 | 自动发现 |
| `ADMOB_TOOLSETS` | 以逗号分隔的工具集列表 | 所有 |
| `ADMOB_READ_ONLY` | `true` 以跳过写入工具 | `false` |
| `ADMOB_CREDENTIALS_DIR` | `oauth_client.json` / `token.json` 的目录 | `~/.admob-mcp` |
| `ADMOB_OAUTH_CLIENT_FILE` | 用于 `auth` 的 OAuth 客户端 JSON 的路径 | `<credentials dir>/oauth_client.json` |
| `GOOGLE_CLIENT_ID` | OAuth 客户端 ID（环境变量登录；也用于 `auth` 代替 JSON 文件） | — |
| `GOOGLE_CLIENT_SECRET` | OAuth 客户端密钥（环境变量登录） | — |
| `GOOGLE_REFRESH_TOKEN` | OAuth 刷新令牌（环境变量登录） | — |
### CLI 标志
| 标志 | 描述 |
| ---------------------- | -------------------------------------------------------- |
| `--toolsets <names>` | 与 `ADMOB_TOOLSETS` 相同，例如 `--toolsets reports,apps` |
| `--read-only` | 与 `ADMOB_READ_ONLY=true` 相同 |
| `--account <pub-id>` | 与 `ADMOB_ACCOUNT` 相同 |
| `--client-file <path>` | 与 `ADMOB_OAUTH_CLIENT_FILE` 相同（用于 `auth`） |
CLI 标志优先于环境变量。
标志位于命令后，在客户端配置中，例如 `npx -y admob-mcp-server --read-only`。
## 工具
“工具”是 AI 助手可以代表您调用的函数。
工具分为五个工具集；默认情况下，所有工具集都已启用，并且 `--read-only` 跳过写入工具：
| 工具集 | 读取工具 | 写入工具（跳过 `--read-only`） |
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `accounts` | `list_accounts`, `get_account` | — |
| `apps` | `list_apps` | `create_app` |
| `adunits` | `list_ad_units` | `create_ad_unit` |
| `reports` | `generate_network_report`, `generate_mediation_report`, `generate_campaign_report` | — |
| `mediation` | `list_ad_sources`, `list_adapters`, `list_mediation_groups`, `list_ad_unit_mappings` | `create_mediation_group`, `update_mediation_group`, `create_ad_unit_mapping`, `create_mediation_ab_experiment`, `stop_mediation_ab_experiment` |
读取工具需要 `admob.readonly` / `admob.report` 范围；写入工具需要 `admob.monetization`（默认情况下在 `auth` 时请求）。
### accounts
| 工具 | 描述 |
| --------------- | -------------------------------------------------------------------------- |
| `list_accounts` | 列出可访问的发布者账户 — 使用它查找您的 `pub-...` ID |
| `get_account` | 获取账户详细信息：发布者 ID、报告货币、报告时区 |
### apps
| 工具 | 描述 |
| ------------ | --------------------------------------------------------------------------------------------- |
| `list_apps` | 列出已注册的应用，包含应用 ID、平台、商店链接和批准状态 |
| `create_app` | 创建应用 — 通过 `appStoreId` 链接商店列表，或通过 `displayName` 手动注册 |
### adunits
| 工具 | 描述 |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `list_ad_units` | 列出广告单元及其 ID、格式和所属应用 |
| `create_ad_unit` | 创建广告单元（`appId`、`displayName`、`adFormat`，可选 `adTypes` / `rewardSettings`） |
### reports
所有报告工具均采用 `startDate` / `endDate`（`YYYY-MM-DD`）、`metrics` 和可选 `dimensions`、`dimensionFilters`、`sortConditions`、`maxReportRows`（默认 1000）和 `currencyCode`。
响应是扁平表格；货币指标从微妙转换为货币单位。
| 工具 | 描述 |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `generate_network_report` | AdMob 网络性能：收入、展示次数、点击次数、匹配率、RPM 等 |
| `generate_mediation_report` | 媒介性能跨广告源：收入、观察到的 eCPM 按 `AD_SOURCE` / `MEDIATION_GROUP` |
| `generate_campaign_report` | 跨推广活动统计数据（仅限最近 30 天）：展示次数、点击次数、安装次数、成本 |
每个报告的有效维度/指标通过 MCP 资源（参考文档，助手可以读取）：`admob://reference/network-report-spec`、`mediation-report-spec`、`campaign-report-spec`。
### mediation
| 工具 | 描述 |
| -------------------------------- | ------------------------------------------------------------------ |
| `list_ad_sources` | 列出可用的媒介广告源（广告网络）和其 ID |
| `list_adapters` | 列出广告源的适配器，包含所需的配置键 |
| `list_mediation_groups` | 列出媒介组和目标和线路（支持 `filter`） |
| `list_ad_unit_mappings` | 列出映射到广告单元的第三方投放 |
| `create_ad_unit_mapping` | 通过适配器将广告单元映射到第三方投放 |
| `create_mediation_group` | 创建媒介组（目标 + 媒介线路） |
| `update_mediation_group` | 使用 `updateMask` 修补媒介组 |
| `create_mediation_ab_experiment` | 在媒介组上启动 A/B 实验 |
| `stop_mediation_ab_experiment` | 停止实验，选择获胜变体 |
## 提示
提示是预制的分析请求。\
您的客户端将它们显示为斜杠命令或提示选择器（例如，Claude Code 中的 `/top_performing_apps`）。\
所有提示都接受一个可选的 `days` 参数：
| 提示 | 功能描述 |
| --------------------- | ---------------------------------------------------------- |
| `top_performing_apps` | 按收入排名的应用，并提供每千次展示收入（RPM）和匹配率的背景信息 |
| `revenue_summary` | 每日收入趋势，突出异常 |
| `compare_ad_formats` | 比较不同广告格式的收益和效率 |
## 安全与隐私
- 服务器完全在您的计算机上运行。\
您的数据仅在您的机器和 Google 的 API 之间流动，绝不会通过任何第三方服务器。
- 两个文件存储在本地，只有您的用户账户可读：`~/.admob-mcp/oauth_client.json`（您的 OAuth 应用）和 `~/.admob-mcp/token.json`（您的登录凭证）。
- **退出登录**：删除 `~/.admob-mcp/token.json`，并可选地在 [myaccount.google.com/permissions](https://myaccount.google.com/permissions) 中撤销应用的访问权限。
- 担心意外更改？\
运行带有 `--read-only` 参数的命令 — 写入工具将完全消失，登录凭证仅请求读取范围。
## 故障排除
### 安装与连接
#### `command not found: npx` / `spawn npx ENOENT`
- **原因**：未安装 Node.js，或客户端无法找到它。
- **解决方法**：从 [nodejs.org](https://nodejs.org) 安装 Node 18+，然后重启客户端。
#### 服务器在客户端中未显示
- **原因**：MCP 服务器在客户端启动时加载，或服务器启动失败。
- **解决方法**：首先重启客户端。\
然后检查其 MCP 状态（Claude Code：`claude mcp list`，Gemini CLI：`/mcp`），并确保 `npx -y admob-mcp-server` 在终端中运行无错误。
### 登录与认证
#### "No usable Google credentials found"
- **原因**：登录凭证尚未设置。
- **解决方法**：按照 [第 2 部分 — 登录](#part-2--sign-in) 中的说明进行操作。
#### `invalid_grant` / "token has been expired or revoked"
- **原因**：您的登录凭证已过期。\
在 **测试** 模式下，带有同意屏幕的凭证每 7 天会发生此情况。
- **解决方法**：重新运行 `npx admob-mcp-server auth`。\
要阻止此情况再次发生，请发布应用（**受众 → 发布应用**）。
#### `access_denied` 在浏览器登录期间
- **原因**：您选择的 Google 账户不是同意屏幕的测试用户。
- **解决方法**：在 **受众 → 测试用户** 下添加它，或发布应用。
#### "The publisher could not be authenticated"
- **原因**：您登录的 Google 账户没有活跃的 AdMob 账户。
- **解决方法**：重新运行 `npx admob-mcp-server auth`，并在账户选择器中选择拥有您的 AdMob 账户的账户。
### API 错误
#### 403 `PERMISSION_DENIED`
- **原因**：AdMob API 未启用、错误的 Google 账户已登录或缺少写入范围。
- **解决方法**：检查以下内容：
1. [AdMob API 已启用](https://console.cloud.google.com/apis/library/admob.googleapis.com)，与您的 OAuth 客户端在同一项目中
2. 您登录了拥有 AdMob 账户的账户
3. 对于写入工具，您的令牌涵盖 `admob.monetization` — `auth --read-only` 的令牌无法写入；重新运行 `npx admob-mcp-server auth`
#### 429 `RESOURCE_EXHAUSTED`
- **原因**：达到 AdMob API 配额（[使用限制](https://developers.google.com/admob/api/limits)）。
- **解决方法**：稍后重试，或减少请求 — 更窄的日期范围，更少的维度。
#### "Multiple AdMob accounts found"
- **原因**：您的 Google 登录凭证可以访问多个发布者账户。
- **解决方法**：设置 `ADMOB_ACCOUNT=pub-...`（使用 `list_accounts` 查找 ID）。
## 开发
```bash
git clone https://github.com/ParkSangGwon/admob-mcp-server.git
cd admob-mcp-server
npm install
npm test
npm run build
# 使用 MCP 检视器进行调试
npm run inspect
```
要在客户端运行本地构建，请将其指向构建入口而不是 npx：`node /path/to/admob-mcp-server/dist/index.js`。
发布：推送 `v*` 标签会运行 CI 并发布到 npm，附带出处（参见 `.github/workflows/release.yml`）。
## 贡献
欢迎提出问题和拉取请求。\
对于较大的更改，请先打开问题讨论方向。\
确保 `npm run lint`、`npm run format:check` 和 `npm test` 通过。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器