🚀 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

Mediation Management — Write Operations

Experiments — A/B Testing

Diagnostics & Optimization

📦 Resources (3)

💡 Prompts (2)

🔒 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)

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

📋 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.