Admob Mcp

🚀 AdMob Model Context Protocol（MCP）サーバー

Google AdMob の管理、メディエーションのウォーターフォール操作、高度な収益分析、A/B テストを、MCP 互換 AI クライアント（Claude Code CLI、Claude Desktop、Cursor、Windsurf、Cline など）に直接提供する、強力な Model Context Protocol（MCP） サーバーです。

ローカルの Rules Engine と Safety Layer を備えており、変更を伴う操作は監査・検証され、実際の 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	メディエーショングループを作成します（最初に Rules Engine による検証を実行）
admob_update_mediation_group	メディエーショングループのターゲティング、ステータス、または広告枠を更新します

実験 — A/B テスト

ツール	説明
admob_create_ab_experiment	メディエーションの A/B テストを作成します
admob_stop_ab_experiment	A/B テストを停止し、勝者となるバリアントを選択します

診断と最適化

ツール	説明
admob_expert_sync	14 日分のメディエーション指標をローカルの SQLite DB に同期します
admob_expert_analyze	根本原因を分析します：フィルレートの異常、マッチ率の低下、収益アラート
admob_recommend_networks_geo	国と広告フォーマットに基づき、Tier 1／Tier 2 のネットワークを推奨します
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 にアクセスする前に 2 段階の安全性パイプラインを通過します。

ステージ 1 — ルールエンジン（rules.py）

ルール	重大度	説明
format_check	🔴 BLOCK	グループの広告フォーマットに対応していないネットワークの追加を防ぎます
child_directed	🔴 BLOCK	COPPA タグ付きアプリでの入札ネットワークをブロックします
min_bidding	🟡 WARN	入札パートナーが 3 社未満の場合に警告します
admob_network_required	🟡 WARN	ウォーターフォールに AdMob Network が含まれていない場合に警告します
pangle_region	🟡 WARN	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 を参照してください。