Admob Mcp

🚀 AdMob 模型上下文协议（MCP）服务

功能强大的**模型上下文协议（MCP）**服务，可将 Google AdMob 管理、中介瀑布流操作、高级收入分析和 A/B 实验直接提供给兼容 MCP 的 AI 客户端（例如 Claude Code CLI、Claude Desktop、Cursor、Windsurf 和 Cline）。

具备本地规则引擎和安全层，确保所有变更操作都经过审计、验证，并在影响线上 AdMob 账号之前先以试运行方式执行。

---

📂 架构概览

MCP-admob/
├── admob_mcp/              ← MCP Server Layer (FastMCP)
│   ├── server.py           ← Server entry point, async context & lifespans
│   ├── resources.py        ← Exposed resources (ad-sources, format-support)
│   ├── prompts.py          ← Integrated workflow prompt templates
│   └── tools/              ← MCP Tool modules
│       ├── reporting.py    ← Read-only reports & network data
│       ├── management.py   ← Mediation Group CRUD
│       ├── experiments.py  ← A/B experiment lifecycles
│       └── diagnostics.py  ← Expert metrics analysis & geo recommendations
├── admob_core/             ← Business Logic & Library Layer
│   ├── client.py           ← Async Google AdMob REST API v1beta wrapper
│   ├── auth.py             ← OAuth 2.0 credential loading & browser flow
│   ├── db.py               ← Local SQLite metrics database (admob_metrics.db)
│   ├── analyzer.py         ← AdMonExpert core diagnostics & sync logic
│   ├── rules.py            ← Mediation policy validator (Rules Engine)
│   ├── safety.py           ← Write safeguard & audit logger
│   └── registry.py         ← 13+ Ad Source capabilities knowledge base
├── config.yaml             ← App categories & rule configuration thresholds
├── requirements.txt        ← Python package dependencies
├── .env.example            ← Template for required environment variables
├── .env                    ← Your secrets (not committed — copy from .env.example)
├── credentials.json        ← OAuth 2.0 Client credentials (not committed — you provide)
└── token.json              ← Authorized OAuth user token (not committed — auto-generated)

---

🛠️ 前置条件与设置

1. 启用 Google AdMob API

1. 打开 Google Cloud Console。
2. 选择或创建项目。
3. 在 API 库中搜索 AdMob API，然后点击启用。

2. 下载 OAuth 2.0 桌面端凭据

1. 前往 API 和服务 → 凭据。
2. 点击创建凭据 → OAuth 客户端 ID。
3. 将应用类型选为 桌面应用。
4. 下载生成的客户端 JSON，并将其保存到此仓库根目录下，命名为 credentials.json。

3. 创建虚拟环境并安装依赖项

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

需要 Python 3.10+。 fastmcp 不支持 Python 3.9 或更早版本。

4. 配置环境（.env）

cp .env.example .env

然后编辑 .env：

PUBLISHER_ID=pub-XXXXXXXXXXXXXXXX      # Your AdMob Publisher ID (AdMob UI → Account)
CREDENTIALS_PATH=credentials.json       # Path to your OAuth credentials file
TOKEN_PATH=token.json                   # Where to cache the authorized token
AUDIT_LOG_PATH=audit.log               # Log file for mutating operations
SLACK_WEBHOOK_URL=                      # (Optional) Slack alert webhook

5. 运行一次性授权流程

python admob_core/auth.py

浏览器标签页将打开 — 使用 Google AdMob 账号进行身份验证并授予权限。此操作会生成 token.json，该文件会被缓存，并在后续每次运行时自动刷新。

---

💻 与 AI 客户端集成

将 /path/to/MCP-admob 替换为你克隆此仓库所在位置的绝对路径。

🤖 Claude Code（CLI）

claude mcp add admob-mediation \
  --env PYTHONPATH="/path/to/MCP-admob" \
  --env PUBLISHER_ID="pub-XXXXXXXXXXXXXXXX" \
  --env CREDENTIALS_PATH="/path/to/MCP-admob/credentials.json" \
  --env TOKEN_PATH="/path/to/MCP-admob/token.json" \
  --env AUDIT_LOG_PATH="/path/to/MCP-admob/audit.log" \
  -- "/path/to/MCP-admob/.venv/bin/python" -m admob_mcp

或者通过 JSON 配置：

claude mcp add-json admob-mediation '{
  "command": "/path/to/MCP-admob/.venv/bin/python",
  "args": ["-m", "admob_mcp"],
  "env": {
    "PYTHONPATH": "/path/to/MCP-admob",
    "PUBLISHER_ID": "pub-XXXXXXXXXXXXXXXX",
    "CREDENTIALS_PATH": "/path/to/MCP-admob/credentials.json",
    "TOKEN_PATH": "/path/to/MCP-admob/token.json",
    "AUDIT_LOG_PATH": "/path/to/MCP-admob/audit.log"
  }
}'

使用 claude mcp list 验证。

---

🖥️ Claude Desktop 应用

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "admob-mediation": {
      "command": "/path/to/MCP-admob/.venv/bin/python",
      "args": ["-m", "admob_mcp"],
      "cwd": "/path/to/MCP-admob",
      "env": {
        "PYTHONPATH": "/path/to/MCP-admob",
        "PUBLISHER_ID": "pub-XXXXXXXXXXXXXXXX",
        "CREDENTIALS_PATH": "/path/to/MCP-admob/credentials.json",
        "TOKEN_PATH": "/path/to/MCP-admob/token.json",
        "AUDIT_LOG_PATH": "/path/to/MCP-admob/audit.log"
      }
    }
  }
}

重启 Claude Desktop 以重新加载。

---

🔍 Cursor IDE

1. 设置 → 功能 → MCP → + 添加新的 MCP 服务
2. 名称：admob-mediation | 类型：command
3. 命令：/path/to/MCP-admob/.venv/bin/python -m admob_mcp
4. 确保项目根目录下的 .env 已填写内容。

---

🌊 Windsurf / Cline / Roo Code

"admob-mediation": {
  "command": "/path/to/MCP-admob/.venv/bin/python",
  "args": ["-m", "admob_mcp"],
  "env": {
    "PYTHONPATH": "/path/to/MCP-admob",
    "PUBLISHER_ID": "pub-XXXXXXXXXXXXXXXX",
    "CREDENTIALS_PATH": "/path/to/MCP-admob/credentials.json",
    "TOKEN_PATH": "/path/to/MCP-admob/token.json",
    "AUDIT_LOG_PATH": "/path/to/MCP-admob/audit.log"
  }
}

---

🧩 MCP 基元参考

🛠️ 工具（共 14 个）

报告 — 只读

工具	描述
admob_list_apps	列出发布商账号中的所有活跃应用
admob_list_ad_units	列出广告单元，可按 app_id 筛选
admob_network_report	按日期、应用、格式和国家统计的广告网络收入报告
admob_mediation_report	按广告网络以及竞价与瀑布流分类的中介收入报告

中介管理 — 写入操作

工具	描述
admob_list_mediation_groups	列出所有中介组及其定向设置和广告位
admob_list_ad_sources	列出 AdMob 支持的所有可用广告网络来源
admob_create_mediation_group	创建中介组（先运行规则引擎验证）
admob_update_mediation_group	更新中介组的定向设置、状态或广告位

实验 — A/B 测试

工具	描述
admob_create_ab_experiment	创建中介 A/B 实验
admob_stop_ab_experiment	停止 A/B 实验并选定胜出变体

诊断与优化

工具	描述
admob_expert_sync	将 14 天的中介指标同步到本地 SQLite 数据库
admob_expert_analyze	根因分析：填充率异常、匹配率下降、收入预警
admob_recommend_networks_geo	针对国家和广告格式推荐一级/二级广告网络
admob_request_placement_map	返回用于 UX/变现规划的广告位映射模板

---

📦 资源（3）

URI	描述
admob://ad-sources	完整的广告网络注册表，支持竞价／瀑布流，并包含来源 ID
admob://app-categories	来自 config.yaml 的应用类别定义和面向儿童的设置
admob://format-support	各广告来源支持的广告格式矩阵（横幅、插页式、激励式等）

---

💡 提示词（2）

提示词	描述
optimize_app(app_id)	逐步审查：同步数据 → 分析 → 检查广告组 → 推荐更改
portfolio_health	全面审查广告组合：标记过期的 A/B 测试、收入下降和缺失的合作伙伴

---

🔒 安全、审计与规则引擎

所有写入操作在访问线上 API 前，都会经过两阶段安全流程：

阶段 1 — 规则引擎（rules.py）

规则	严重程度	描述
format_check	🔴 BLOCK	阻止添加不支持该广告组广告格式的网络
child_directed	🔴 BLOCK	阻止在标记为 COPPA 的应用中使用竞价网络
min_bidding	🟡 WARN	配置的竞价合作伙伴少于 3 个时发出提醒
admob_network_required	🟡 WARN	瀑布流中缺少 AdMob Network 时发出警告
pangle_region	🟡 WARN	在 Pangle 优势地区以外添加 Pangle 时发出警告（APAC、US、BR、MX）

阶段 2 — 快照与审计日志（safety.py）

• 对任何写入工具设置 dry_run=True，即可预览更改，而不会调用 API
• 每次实际变更都会生成变更前快照，并将结构化 JSON 条目追加到 audit.log

---

⚙️ 配置（config.yaml）

自定义应用类别和规则阈值：

app_categories:
  gaming:
    app_ids: ["ca-app-pub-XXXX~YYYY"]   # AdMob app IDs to tag
    child_directed: false
    primary_formats: ["REWARDED_VIDEO", "INTERSTITIAL", "BANNER"]

rules:
  min_bidding_partners: 3
  stale_ecpm_threshold_days: 30
  stale_experiment_days: 14

---

❌ 故障排除

错误	解决方法
ValueError: PUBLISHER_ID must be provided	检查 .env 是否包含 PUBLISHER_ID=pub-...，并确认服务器的 cwd 指向仓库根目录
FileNotFoundError: credentials.json not found	将 credentials.json 放在仓库根目录，或将 CREDENTIALS_PATH 设置为其绝对路径
403 Forbidden / AdMob API not enabled	在项目的 Google Cloud Console 中启用 AdMob API
401 Unauthorized / Token Expired	删除 token.json，然后重新运行 python admob_core/auth.py
fastmcp not found / install errors	确认使用的是 Python 3.10+（python --version）

---

📋 要求

• Python 3.10+
• 已启用 AdMob API 的 Google Cloud 项目
• OAuth 2.0 桌面应用凭据（credentials.json）
• 有效的 AdMob 发布商账号

---

📄 许可证

MIT — 参见 LICENSE。