# admob-mcp

[![CI](https://github.com/jerry2247/admob-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jerry2247/admob-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A Model Context Protocol (MCP) server for the Google AdMob API. It gives MCP clients such as Claude Code, Cursor, Codex, and other agents a set of typed tools for reading AdMob accounts, apps, ad units, mediation settings, and reports, plus write tools for the operations the AdMob API supports. Reads run freely; every write requires your confirmation.

This project is API first. It only exposes operations that the official AdMob API actually supports, and it clearly documents the surfaces that AdMob keeps in the UI with no API.

## Status

Version 0.1.0. Local stdio server with desktop OAuth. Not yet published to npm.

## What it can do

Everything here is backed by the official AdMob API (`admob.googleapis.com`).

### Read tools (safe, run without confirmation)

| Tool | Purpose |
| --- | --- |
| `admob_list_accounts` | List the signed-in AdMob publisher account. |
| `admob_get_account` | Get one account (publisher id, time zone, currency). |
| `admob_list_apps` | List apps under an account. |
| `admob_list_ad_units` | List ad units under an account. |
| `admob_list_ad_sources` | List mediation ad sources. |
| `admob_list_adapters` | List the adapters for one ad source. |
| `admob_list_ad_unit_mappings` | List ad unit mappings for one ad unit. |
| `admob_list_mediation_groups` | List mediation groups (supports a filter). |
| `admob_run_network_report` | Generate an AdMob Network report. |
| `admob_run_mediation_report` | Generate an AdMob Mediation report. |
| `admob_run_campaign_report` | Generate an AdMob campaign report (v1beta). |

### Write tools (require confirmation, support dry run)

| Tool | Purpose |
| --- | --- |
| `admob_create_app` | Create an app. |
| `admob_create_ad_unit` | Create an ad unit. |
| `admob_create_ad_unit_mapping` | Map an ad unit to a mediation adapter. |
| `admob_batch_create_ad_unit_mappings` | Create up to 100 ad unit mappings at once. |
| `admob_create_mediation_group` | Create a mediation group. |
| `admob_update_mediation_group` | Update a mediation group (patch with update mask). |
| `admob_create_ab_experiment` | Start a mediation A/B experiment. |
| `admob_stop_ab_experiment` | Stop a mediation A/B experiment and pick a variant. |

All write tools are AdMob API v1beta methods. Google gates these behind allowlisted access, so a write may return a 403 until your AdMob account is granted access by your account manager. The server turns that 403 into a clear message.

### Not supported (no AdMob API)

These AdMob surfaces have no public API, so this server does not implement them. It does not use browser automation. Use the AdMob web UI for:

app-ads.txt diagnostics, blocking controls, privacy and messaging (UMP consent messages), policy center, test devices, crawler access, change history, AdMob Labs, payments and payouts, users and roles, linked services (Firebase, Ad Manager, Analytics), app verification, and account cancellation.

Read the `admob://capabilities` resource for the machine-readable version of this map.

## Safety model

The safety boundary is the same idea as your client asking permission before it runs a command.

- Read tools are annotated `readOnlyHint`, so clients can run them without a prompt.
- Write tools are annotated `destructiveHint` and carry the Claude Code `requiresUserInteraction` hint, which forces an approval prompt on every call and cannot be bypassed by auto accept modes. Other clients prompt on destructive tools as well.
- Every write tool accepts `dryRun: true`, which returns the exact request that would be sent without executing it.
- Set `ADMOB_READONLY=1` to disable all write tools. They are then not registered at all.

## Requirements

- Node.js 18 or newer.
- A Google account with an AdMob account.
- A Google Cloud project with the AdMob API enabled and an OAuth client.

## Setup

### 1. Enable the AdMob API and create an OAuth client

1. In the Google Cloud console, enable the AdMob API for your project.
2. Configure the OAuth consent screen. For personal use, set the user type to External, keep the publishing status in Testing, and add your Google account as a test user. Note that in Testing mode refresh tokens expire after 7 days; publish the app for long lived tokens.
3. Create an OAuth client of type Desktop app. Note the client id and client secret.

The AdMob scopes are sensitive, not restricted. A published multi user app needs Google sensitive scope verification, but there is no annual security assessment for these scopes.

### 2. Install

Until this package is published to npm, clone and build it:

```bash
git clone https://github.com/jerry2247/admob-mcp.git
cd admob-mcp
npm install
npm run build
```

### 3. Authenticate

Provide your OAuth client in the environment and run the auth command. It opens a browser using a loopback redirect with PKCE and stores a refresh token.

```bash
export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-client-secret"
node dist/index.js auth
```

The refresh token is saved to `~/.config/admob-mcp/credentials.json` with 0600 permissions. Run `node dist/index.js logout` to remove it.

### 4. Configure your MCP client

For Claude Code, add a project `.mcp.json` (see `examples/mcp.json`):

```json
{
  "mcpServers": {
    "admob": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/admob-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}"
      }
    }
  }
}
```

The `${VAR}` values are expanded by Claude Code from your shell environment, so no secret is committed. Credentials from `admob-mcp auth` are read from the stored file, so you do not need to pass a refresh token. To run read only, add `"ADMOB_READONLY": "1"` to `env`. To fix the default account, add `"ADMOB_PUBLISHER_ID": "pub-1234567890123456"`.

The same server works in other clients. Cursor and VS Code use the same `mcpServers` shape. Codex uses TOML, for example:

```toml
[mcp_servers.admob]
command = "node"
args = ["/absolute/path/to/admob-mcp/dist/index.js"]

[mcp_servers.admob.env]
GOOGLE_CLIENT_ID = "your-client-id"
GOOGLE_CLIENT_SECRET = "your-client-secret"
```

## Resources and prompts

Resources:

- `admob://capabilities` - what is API backed versus UI only or human only.
- `admob://enums/reports` - allowed dimensions and metrics for each report type.
- `admob://account` - the current account summary.

Prompts:

- `admob_revenue_review` - guide a revenue review over a date range using the network and mediation reports.
- `admob_setup_check` - verify credentials and summarize available capabilities.

## Reporting

Report tools take a date range (YYYY-MM-DD), a list of dimensions, and one or more metrics. The allowed values differ per report type and are listed in each tool description and in the `admob://enums/reports` resource. Network and mediation reports are generated as a stream and normalized into rows. The campaign report is v1beta only and limited to a 30 day range. Tool results include a row count and a capped set of rows to keep output small; raise `limit` to include more.

## Environment variables

| Variable | Purpose |
| --- | --- |
| `GOOGLE_CLIENT_ID` | OAuth client id. Required. |
| `GOOGLE_CLIENT_SECRET` | OAuth client secret. Optional for Desktop clients but usually set. |
| `ADMOB_REFRESH_TOKEN` | Refresh token supplied directly, skipping the stored file. |
| `ADMOB_PUBLISHER_ID` | Default account, for example `pub-1234567890123456`. |
| `ADMOB_READONLY` | Set to `1` to disable all write tools. |
| `ADMOB_MCP_CREDENTIALS_PATH` | Override the stored credentials file path. |
| `ADMOB_MCP_LOG_LEVEL` | `debug`, `info` (default), `warn`, or `error`. |

## Security notes

- Secrets are read from the environment. The `.mcp.json` example keeps them out of version control with `${VAR}` expansion.
- The only secret stored at rest is the OAuth refresh token, written with 0600 permissions outside the repository.
- The server writes only JSON-RPC to stdout. All logs go to stderr.
- The server requests least privilege scopes: `admob.readonly` only, plus `admob.monetization` when writes are enabled.

## Development

```bash
npm run build       # compile TypeScript to dist
npm run typecheck   # type check without emitting
npm test            # build then run the vitest suite
npm run format      # format with prettier
npm run inspector   # build then open the MCP Inspector against the server
```

Tests are fully mocked and do not call the AdMob API.

## Known limitations and roadmap

- v1 of the AdMob API is read only. All writes are v1beta and allowlisted, so writes may return 403 until Google grants your account access.
- No hosted HTTP transport yet. v0.1 is local stdio only.
- No OS keychain storage yet. The refresh token is stored in a 0600 file.
- No browser or UI fallback for the surfaces that have no API.

## License

MIT. See [LICENSE](LICENSE).