admob-mcp-server

AdMob MCP 服务

English | 한국어

用日常语言询问 AI 助手有关 AdMob 应用和收入的问题：

• “过去 7 天，我的应用赚了多少钱？按国家细分。”
• “本月哪个广告变现来源的 eCPM 最高？”
• “比较横幅广告与激励广告单元的 RPM。”
• “列出我的应用及其广告单元。”

这是适用于 Google AdMob API 的 Model Context Protocol (MCP) 服务。
它可与 Claude Code、Claude Desktop、Cursor、Gemini CLI 以及任何其他支持 MCP 的 AI 客户端配合使用。

架构

flowchart LR
    C["MCP client<br/>Claude Code · Claude Desktop · Cursor · Gemini CLI"]

    subgraph S["admob-mcp-server — runs on your machine"]
        direction TB
        T["9 read-only tools in 5 toolsets<br/>accounts · apps · adunits · reports · mediation<br/>(filtered by --toolsets)"]
        A["Credential resolver<br/>env vars → token.json → gcloud ADC"]
        R["Report flattener<br/>chunk stream → rows · micros → currency"]
    end

    G["Google AdMob API<br/>v1beta"]

    C <-->|"MCP over stdio"| T
    T --> A
    A <-->|"OAuth 2.0 / HTTPS"| G
    G -.->|"report chunks"| R
    R -.-> T

凭据和收入数据只会在你的设备与 Google 之间传输，中间没有任何第三方服务。

功能

• 涵盖 AdMob API 向普通账号开放的所有功能 — 提供 9 个工具，覆盖账号、应用、广告单元、报告和变现（为什么没有写入工具）
• 报告清晰易读 — 将流式报告响应整理成简单的行表，并将货币值（微单位）转换为实际货币单位
• 专为只读而设计 — 登录时仅请求读取权限，因此服务无法更改 AdMob 账号中的任何内容
• 工具集 — 仅启用所需的工具组，例如 --toolsets reports,accounts
• 三种身份验证方式 — 一条命令即可在浏览器中登录（npx admob-mcp-server auth）、使用环境变量中的刷新令牌，或使用 gcloud Application Default Credentials
• 内置分析提示词和报告规范参考资源

快速了解设置流程

一次性设置，大约需要 10 分钟：

要求

• Node.js 18 或更高版本 — 使用 node --version 检查；如果尚未安装，请从 nodejs.org 安装
• 一个 AdMob 账号，以及拥有该账号的 Google 账号

设置

第 1 部分 — Google Cloud 设置

为什么需要这一步？
AdMob API 没有简单的 API 密钥——Google 要求每个访问你数据的程序都注册为一个“O​​Auth 应用”。
在这里，你要注册一个仅供自己使用的个人应用。
这是免费的，也无需设置结算信息。

1. 创建或选择一个 Google Cloud 项目：console.cloud.google.com/projectcreate — 名称任意；也可以重复使用现有项目。
2. 启用 AdMob API：console.cloud.google.com/apis/library/admob.googleapis.com → 检查顶部栏中是否已选中你的项目 → 启用。
3. 配置 OAuth 同意屏幕：console.cloud.google.com/auth/overview — 首次访问时会打开一个简短的向导：
   • 应用名称：任意（例如 admob-mcp），并填写你的电子邮件作为支持/联系邮箱
   • 受众群体：外部
   • 完成向导 — 无需将应用提交给 Google 验证
   • 然后前往 受众群体 → 测试用户 → 添加用户，添加拥有你的 AdMob 账号的 Google 账号
4. 创建 OAuth 客户端：console.cloud.google.com/apis/credentials → 创建凭据 → OAuth 客户端 ID
   • 应用类型：桌面应用
   • 创建后，点击 下载 JSON — 第 2 部分会用到这个文件

警告

同意屏幕处于测试模式时，Google 会在 7 天后使登录失效，因此你需要每周重新登录。
要避免这种情况，请发布应用（受众群体 → 发布应用）。
发布供自己使用的应用无需通过 Google 验证 — 登录时只会看到“此应用未经验证”的警告，这是正常的。

第 2 部分 — 登录

将下载的 JSON 文件移到服务查找该文件的位置，然后运行登录命令：

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 部分创建的应用 — 点击“继续”。
当终端显示 Setup complete 时，你的登录信息会保存到 ~/.admob-mcp/token.json，之后会重复使用。

登录请求 admob.readonly 和 admob.report 范围 — 仅有读取权限。

auth 命令的作用：

sequenceDiagram
    autonumber
    participant T as Terminal
    participant S as admob-mcp-server
    participant B as Browser
    participant G as Google

    T->>S: npx admob-mcp-server auth
    S->>S: read ~/.admob-mcp/oauth_client.json
    S->>B: open consent URL (loopback redirect, random port)
    B->>G: sign in & allow scopes
    G-->>S: authorization code → refresh token
    S->>S: save ~/.admob-mcp/token.json (reused for every later call)

export GOOGLE_CLIENT_ID="....apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="..."
export GOOGLE_REFRESH_TOKEN="..."

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/cloud-platform \
  --client-id-file=path/to/oauth_client.json

凭据解析顺序：环境变量 → token.json（来自 auth）→ ADC。

第 3 部分 — 连接 AI 客户端

请从下方选择你的客户端。
MCP 服务会在客户端启动时加载，因此添加配置后请重启客户端。

Claude Code

claude mcp add admob -- npx -y admob-mcp-server

使用 claude mcp list 验证——你应该会看到 admob: ... - ✔ Connected。

Claude Desktop — 打开 Settings → Developer → Edit Config，这会打开 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\），然后添加：

{
  "mcpServers": {
    "admob": {
      "command": "npx",
      "args": ["-y", "admob-mcp-server"]
    }
  }
}

重启应用；admob 工具会出现在聊天输入框的工具菜单中。

Cursor — 将相同的 mcpServers 区块添加到 ~/.cursor/mcp.json，然后检查 Settings → MCP 中的 admob 是否已启用。

Gemini CLI — 将相同的 mcpServers 区块添加到 ~/.gemini/settings.json，然后在 CLI 中使用 /mcp 检查。

提示

如果你使用环境变量登录，请通过客户端的 env 区块传递这些变量（Claude Code：在 -- 前重复添加 --env KEY=value；JSON 配置：在 "args" 旁添加 "env": { ... } 对象）。

试用

你无需亲自调用工具——只需用自然语言提问，助手就会选择合适的工具。
可以试试这些问题：

• “我的应用上周收入是多少？”
• “按国家和应用拆分本月收入。”
• “过去 30 天内，哪种广告格式的 RPM 最高？”
• “我的中介效果如何？比较各广告来源的观察 eCPM。”
• “列出我的应用及其广告单元。”

大多数客户端会在每次工具调用前征求你的许可，因此未经你批准不会运行任何内容。

配置

所有配置均为可选项——默认设置适用于单个 AdMob 账号。

环境变量

CLI 标志

CLI 标志的优先级高于环境变量。
在客户端配置中，标志应放在命令后面，例如 npx -y admob-mcp-server --toolsets reports。

工具

“工具”是 AI 助手可以代你调用的函数。
工具分为五个工具集；默认情况下均已启用：

所有工具均为只读，并且需要 admob.readonly / admob.report 权限范围。

为什么没有写入工具

AdMob API 确实提供写入方法（adUnits.create、apps.create，以及整个 mediationGroups 资源），但 Google 将它们都标记为受限访问：

此方法的访问权限受限。如果你遇到 403 权限被拒绝错误，请联系你的客户经理以获取访问权限。

即使使用有效的 admob.monetization 令牌，普通发布者账号调用这些方法也会收到 PERMISSION_DENIED；同样的限制也会阻止调用 mediationGroups.list 和 adUnitMappings.list，尽管它们是读取操作。由于这些工具必须使用已列入许可名单的账号才能正常工作，因此我们不会提供这些工具：看到它们的助手会尝试调用并失败。请改在 AdMob 控制台中创建广告单元和中介组。

accounts

apps

adunits

reports

所有报告工具都接受 startDate / endDate（YYYY-MM-DD）、metrics，以及可选的 dimensions、dimensionFilters、sortConditions、maxReportRows（默认值为 1000）、currencyCode。
响应为扁平表格；货币指标会从微单位转换为货币单位。

每种报告支持的维度/指标均通过 MCP 资源公开（助手可读取的参考文档）：admob://reference/network-report-spec、mediation-report-spec、campaign-report-spec。

mediation

调解组和广告单元映射不在涵盖范围内——请参阅为什么没有写入工具。

提示词

提示词是现成的分析请求。
客户端会将它们显示为斜杠命令或提示词选择器（例如，Claude Code 中的 /top_performing_apps）。
所有提示词都接受可选的 days 参数：

安全与隐私

• 服务完全在你的计算机上运行。
  你的数据只会在你的设备和 Google API 之间传输，不会经过任何第三方服务。
• 两个文件会存储在本地，且只有你的用户帐户可以读取：~/.admob-mcp/oauth_client.json（你的 OAuth 应用）和 ~/.admob-mcp/token.json（你的登录凭据）。
• 退出登录：删除 ~/.admob-mcp/token.json，并可选择在 myaccount.google.com/permissions 撤销应用的访问权限。
• 无法修改任何内容：登录请求仅申请读取范围，且所有工具均为只读。

故障排除

安装与连接

command not found: npx / spawn npx ENOENT

• 原因：未安装 Node.js，或客户端无法找到它。
• 解决方法：从 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 部分——登录操作。

invalid_grant / "token has been expired or revoked"

• 原因：你的登录凭据已过期。
  如果同意屏幕处于测试模式，这种情况每 7 天就会发生一次。
• 解决方法：重新运行 npx admob-mcp-server auth。
  若要避免再次发生，请发布应用（Audience → Publish app）。

浏览器登录时出现 access_denied

• 原因：你选择的 Google 帐户不是同意屏幕的测试用户。
• 解决方法：在 Audience → Test users 下添加该帐户，或发布应用。

"The publisher could not be authenticated"

• 原因：你登录使用的 Google 帐户没有有效的 AdMob 帐户。
• 解决方法：重新运行 npx admob-mcp-server auth，并在帐户选择器中选择拥有 AdMob 帐户的帐户。

API 错误

403 PERMISSION_DENIED

• 原因：未启用 AdMob API、登录时使用了错误的 Google 帐户，或令牌是在范围变更前生成的。
• 解决方法：检查以下事项：
  1. 在与 OAuth 客户端相同的项目中启用了 AdMob API
  2. 你使用拥有 AdMob 帐户的帐户登录
  3. 你的令牌包含 admob.readonly 和 admob.report 范围——重新运行 npx admob-mcp-server auth 以刷新令牌

429 RESOURCE_EXHAUSTED

• 原因：已达到 AdMob API 配额（使用限制）。
• 解决方法：稍后重试，或缩小请求范围——缩短日期范围、减少维度。

“找到多个 AdMob 账号”

• 原因：你的 Google 登录账号可以访问多个发布商账号。
• 解决方法：设置 ADMOB_ACCOUNT=pub-...（使用 list_accounts 查找 ID）。

开发

git clone https://github.com/ParkSangGwon/admob-mcp-server.git
cd admob-mcp-server
npm install
npm test
npm run build

# debug with the MCP Inspector
npm run inspect

要在客户端中运行本地构建，请将其指向已构建的入口文件，而不是 npx：node /path/to/admob-mcp-server/dist/index.js。

发布：推送 v* 标签会运行 CI，并使用 provenance 发布到 npm（参见 .github/workflows/release.yml）。

贡献

欢迎提交问题和拉取请求。
对于较大的改动，请先提交问题，讨论方向。
请确保 npm run lint、npm run format:check 和 npm test 均通过。

许可证

MIT