# Google AdMob Manager MCP Server

[![npm version](https://img.shields.io/npm/v/@w3wide/admob-manager-mcp.svg)](https://www.npmjs.com/package/@w3wide/admob-manager-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Model Context Protocol](https://img.shields.io/badge/MCP-v2.0-blue.svg)](https://modelcontextprotocol.io)

An enterprise-grade **Model Context Protocol (MCP)** server providing complete control over **Google AdMob REST API (`v1beta`)**. Designed for AI Agents (Claude Desktop, Cursor, Antigravity/AGY) to automate AdMob publisher account management, apps, ad units, mediation groups, A/B experiments, bidding ad unit mappings, and performance reporting.

---

## 🌟 Key Features

- **19 Complete REST API Tools**: Full matrix covering Accounts, Apps, Ad Units, Ad Unit Mappings, Mediation Groups, A/B Experiments, and Performance Reports.
- **Zero-Config Auto Browser OAuth 2.0**: Embedded Google OAuth 2.0 Client credentials (`w3wide-auth-services`). Automatically opens your system browser for one-click Google AdMob login when unauthenticated.
- **Auto Silent Token Refresh**: Tokens are cached at `~/.config/admob-manager-mcp/tokens.json` and silently refreshed automatically.
- **Resilient 401/403 Auto-Retry**: If tokens expire or permissions change, the server purges cached tokens and seamlessly re-prompts browser authorization.
- **Dual Transport Mode**: Supports both standard Stdio transport (`npm run mcp`) and Streamable HTTP transport with MCP v2 Native Auth (`npm run mcp:http`).
- **Third-Party Bidding Mapping**: Associate Meta Audience Network, Unity Ads, AppLovin, and ironSource Placement IDs with AdMob Ad Units.

---

## 🚀 Quickstart & Installation

### Option 1: Run via NPX (Zero Install)

```bash
npx @w3wide/admob-manager-mcp
```

### Option 2: Global Installation

```bash
npm install -g @w3wide/admob-manager-mcp
admob-manager-mcp
```

---

## ⚙️ MCP Client Configuration Examples

### 1. Claude Desktop Configuration

Add the following to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
    "mcpServers": {
        "admob-manager": {
            "command": "npx",
            "args": ["-y", "@w3wide/admob-manager-mcp"]
        }
    }
}
```

---

### 2. Cursor Configuration (`.cursor/mcp.json` or Global Settings)

Add to `.cursor/mcp.json` in your project or global Cursor MCP settings:

```json
{
    "mcpServers": {
        "admob-manager": {
            "command": "npx",
            "args": ["-y", "@w3wide/admob-manager-mcp"]
        }
    }
}
```

---

### 3. Antigravity / AGY / Local MCP Configuration (`mcp.json`)

Create `mcp.json` in your workspace directory:

```json
{
    "mcpServers": {
        "admob-manager-mcp": {
            "command": "node",
            "args": ["/absolute/path/to/admob-manager-mcp/dist/index.js"]
        }
    }
}
```

---

## 🔐 Authentication & Google Cloud Setup

1. **Embedded OAuth Client**: Out of the box, the server uses embedded Google OAuth 2.0 Client credentials linked to `w3wide-auth-services` GCP project.
2. **First Run**: When an AI agent executes an AdMob tool, if `~/.config/admob-manager-mcp/tokens.json` does not exist:
    - The server spins up a local callback listener on `http://localhost:3000/oauth2callback`.
    - Your default browser automatically pops up Google's OAuth consent screen.
    - Select your Google Account and click **Allow**.
    - Tokens are saved locally, and all future tool calls execute seamlessly.

---

## 🛠️ Complete MCP Tools Matrix (19 Tools)

| Tool Name                          | Description                                       | Key Parameters                                |
| :--------------------------------- | :------------------------------------------------ | :-------------------------------------------- |
| `getAdmobAccount`                  | Get AdMob publisher account details               | `publisherId`                                 |
| `listAdmobAccounts`                | List all AdMob publisher accounts                 | `pageSize`, `pageToken`                       |
| `listAdmobAdSources`               | List supported ad sources for mediation           | `publisherId`, `pageSize`                     |
| `listAdmobAdSourceAdapters`        | List adapters for a specific ad source            | `adSourceParent`, `pageSize`                  |
| `listAdmobApps`                    | List all apps linked to publisher account         | `publisherId`, `pageSize`                     |
| `createAdmobApp`                   | Create a new AdMob app                            | `publisherId`, `app`                          |
| `listAdmobAdUnits`                 | List ad units for an account                      | `publisherId`, `filter`                       |
| `createAdmobAdUnit`                | Create a new Banner/Interstitial/Rewarded ad unit | `publisherId`, `adUnit`                       |
| `listAdmobAdUnitMappings`          | List bidding mappings for an ad unit              | `adUnitName`, `filter`                        |
| `createAdmobAdUnitMapping`         | Create bidding mapping for Meta/Unity/AppLovin    | `adUnitName`, `adUnitMapping`                 |
| `batchCreateAdmobAdUnitMappings`   | Batch create up to 100 ad unit mappings           | `publisherId`, `requests`                     |
| `listAdmobMediationGroups`         | List mediation groups                             | `publisherId`, `filter`                       |
| `createAdmobMediationGroup`        | Create a mediation group                          | `publisherId`, `mediationGroup`               |
| `patchAdmobMediationGroup`         | Update an existing mediation group                | `mediationGroupName`, `mediationGroup`        |
| `createAdmobMediationAbExperiment` | Start an A/B mediation experiment                 | `mediationGroupName`, `mediationAbExperiment` |
| `stopAdmobMediationAbExperiment`   | Stop an active A/B experiment                     | `experimentName`, `variantChoice`             |
| `generateAdmobNetworkReport`       | Generate AdMob Network performance report         | `publisherId`, `reportSpec`                   |
| `generateAdmobMediationReport`     | Generate Mediation revenue & match rate report    | `publisherId`, `reportSpec`                   |
| `generateAdmobCampaignReport`      | Generate Campaign performance report              | `publisherId`, `reportSpec`                   |

---

## 🧪 Testing with MCP Inspector

Inspect and test all tools interactively in your browser:

```bash
npm run inspector
```

Opens `http://localhost:5173` (or active inspector port) with full tool execution UI and parameter schema validation.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).