Admob Mcp

🚀 AdMob Model Context Protocol (MCP) Server

A powerful Model Context Protocol (MCP) server that exposes Google AdMob management, mediation waterfall operations, advanced revenue analysis, and A/B experiments directly to MCP-compatible AI clients (such as Claude Code CLI, Claude Desktop, Cursor, Windsurf, and Cline).

Features a local Rules Engine and Safety Layer ensuring that mutating operations are audited, verified, and run via dry-runs before touching your live AdMob account.

---

📂 Architecture Overview

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)

---

🛠️ Prerequisites & Setup

1. Enable the Google AdMob API

1. Open the Google Cloud Console.
2. Select or create your project.
3. Search for AdMob API in the API Library and click Enable.

2. Download OAuth 2.0 Desktop Credentials

1. Navigate to APIs & Services → Credentials.
2. Click Create Credentials → OAuth client ID.
3. Select Desktop app as the Application Type.
4. Download the generated client JSON and save it in the root of this repo as credentials.json.

3. Create Virtual Environment & Install Dependencies

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

Python 3.10+ required. fastmcp does not support Python 3.9 or older.

4. Configure Environment (.env)

cp .env.example .env

Then edit .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. Run the One-time Authorization Flow

python admob_core/auth.py

A browser tab will open — authenticate with your Google AdMob account and grant permissions. This writes token.json which is cached and auto-refreshed on all subsequent runs.

---

💻 Integrating with AI Clients

Replace /path/to/MCP-admob with the absolute path to wherever you cloned this repo.

🤖 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

Or via 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"
  }
}'

Verify with claude mcp list.

---

🖥️ Claude Desktop App

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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"
      }
    }
  }
}

Restart Claude Desktop to reload.

---

🔍 Cursor IDE

1. Settings → Features → MCP → + Add New MCP Server
2. Name: admob-mediation | Type: command
3. Command: /path/to/MCP-admob/.venv/bin/python -m admob_mcp
4. Ensure your .env is populated in the project root.

---

🌊 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 Primitives Reference

🛠️ Tools (14 total)

Reporting — Read-Only

Tool	Description
admob_list_apps	Lists all active apps in the publisher account
admob_list_ad_units	Lists ad units, optionally filtered by app_id
admob_network_report	Network revenue report across dates, apps, formats, countries
admob_mediation_report	Mediation revenue report broken down by network, bidding vs waterfall

Mediation Management — Write Operations

Tool	Description
admob_list_mediation_groups	Lists all mediation groups with targeting and line items
admob_list_ad_sources	Lists available ad network sources supported by AdMob
admob_create_mediation_group	Creates a mediation group (runs Rules Engine validation first)
admob_update_mediation_group	Updates targeting, status, or line items of a mediation group

Experiments — A/B Testing

Tool	Description
admob_create_ab_experiment	Creates a mediation A/B experiment
admob_stop_ab_experiment	Stops an A/B experiment and selects the winner variant

Diagnostics & Optimization

Tool	Description
admob_expert_sync	Syncs 14 days of mediation metrics into the local SQLite DB
admob_expert_analyze	Root-cause analysis: fill rate anomalies, match rate drops, revenue alerts
admob_recommend_networks_geo	Tier-1/Tier-2 network recommendations for a country + ad format
admob_request_placement_map	Returns a placement mapping template for UX/monetization planning

---

📦 Resources (3)

URI	Description
admob://ad-sources	Full ad network registry with bidding/waterfall support and source IDs
admob://app-categories	App category definitions and child-directed settings from config.yaml
admob://format-support	Format support matrix per ad source (banner, interstitial, rewarded, etc.)

---

💡 Prompts (2)

Prompt	Description
optimize_app(app_id)	Step-by-step audit: sync data → analyze → inspect groups → recommend changes
portfolio_health	Portfolio-wide audit: flags stale A/B tests, revenue drops, missing partners

---

🔒 Safety, Auditing & Rules Engine

All write operations go through a two-stage safety pipeline before touching the live API:

Stage 1 — Rules Engine (rules.py)

Rule	Severity	Description
format_check	🔴 BLOCK	Prevents adding a network that doesn't support the group's ad format
child_directed	🔴 BLOCK	Blocks bidding networks on COPPA-tagged apps
min_bidding	🟡 WARN	Alerts when fewer than 3 bidding partners are configured
admob_network_required	🟡 WARN	Warns if AdMob Network is absent from the waterfall
pangle_region	🟡 WARN	Warns if Pangle is added outside its strong geos (APAC, US, BR, MX)

Stage 2 — Snapshot + Audit Log (safety.py)

• dry_run=True on any write tool previews the change without hitting the API
• Every real mutation captures a pre-change snapshot and appends a structured JSON entry to audit.log

---

⚙️ Configuration (config.yaml)

Customize app categories and rule thresholds:

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

---

❌ Troubleshooting

Error	Fix
ValueError: PUBLISHER_ID must be provided	Check .env contains PUBLISHER_ID=pub-... and that the server's cwd points to the repo root
FileNotFoundError: credentials.json not found	Place credentials.json in the repo root or set CREDENTIALS_PATH to its absolute path
403 Forbidden / AdMob API not enabled	Enable the AdMob API in Google Cloud Console for your project
401 Unauthorized / Token Expired	Delete token.json and re-run python admob_core/auth.py
fastmcp not found / install errors	Ensure you're using Python 3.10+ (python --version)

---

📋 Requirements

• Python 3.10+
• Google Cloud project with AdMob API enabled
• OAuth 2.0 Desktop App credentials (credentials.json)
• An active AdMob publisher account

---

📄 License

MIT — see LICENSE.