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](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ard3051997
• Source: ard3051997/Admob-MCP
• License: MIT

Install and usage instructions live in the source repository linked above.