# Admob Mcp Server

> MCP server for the Google AdMob API — apps, ad units, mediation, and revenue reports

- **Type:** MCP server
- **Install:** `agentstack add mcp-parksanggwon-admob-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ParkSangGwon](https://agentstack.voostack.com/s/parksanggwon)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ParkSangGwon](https://github.com/ParkSangGwon)
- **Source:** https://github.com/ParkSangGwon/admob-mcp-server

## Install

```sh
agentstack add mcp-parksanggwon-admob-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AdMob MCP Server

[](https://www.npmjs.com/package/admob-mcp-server)
[](https://github.com/ParkSangGwon/admob-mcp-server/actions/workflows/ci.yml)
[](LICENSE)

**English** | [한국어](README.ko.md)

Ask your AI assistant about your AdMob apps and earnings — in plain language:

> - "How much did my apps earn in the last 7 days, broken down by country?"
> - "Which mediation ad source had the best eCPM this month?"
> - "Compare the RPM of my banner vs. rewarded ad units."
> - "Create a rewarded ad unit for my new game."

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Google AdMob API](https://developers.google.com/admob/api).\
It works with Claude Code, Claude Desktop, Cursor, Gemini CLI, and any other MCP-capable AI client.

## Architecture

```mermaid
flowchart LR
    C["MCP clientClaude Code · Claude Desktop · Cursor · Gemini CLI"]

    subgraph S["admob-mcp-server — runs on your machine"]
        direction TB
        T["18 tools in 5 toolsetsaccounts · apps · adunits · reports · mediation(filtered by --toolsets / --read-only)"]
        A["Credential resolverenv vars → token.json → gcloud ADC"]
        R["Report flattenerchunk stream → rows · micros → currency"]
    end

    G["Google AdMob APIv1beta"]

    C |"MCP over stdio"| T
    T --> A
    A |"OAuth 2.0 / HTTPS"| G
    G -.->|"report chunks"| R
    R -.-> T
```

Credentials and revenue data travel only between your machine and Google — there is no third-party server in between.

## Features

- **Full AdMob API v1beta coverage** — 18 tools across accounts, apps, ad units, reports, and mediation, including write operations the v1 API doesn't have
- **Reports made readable** — streaming report responses are flattened into simple row tables, and monetary values (micros) are converted to real currency units
- **Read-only mode when you want it** — pass `--read-only` to hide all write tools (create/update) and issue tokens that can't modify anything
- **Toolsets** — enable only the tool groups you need, e.g. `--toolsets reports,accounts`
- **Three authentication options** — one-command browser sign-in (`npx admob-mcp-server auth`), environment-variable refresh token, or gcloud Application Default Credentials
- **Built-in analysis prompts** and report-spec reference resources

## Setup at a glance

One-time setup, roughly 10 minutes:

| Step                                                         | What you do                                                       | Where    |
| ------------------------------------------------------------ | ----------------------------------------------------------------- | -------- |
| [1. Google Cloud setup](#part-1--google-cloud-setup)         | Register a personal "app" so Google lets you access your own data | browser  |
| [2. Sign in](#part-2--sign-in)                               | Run one command and log in with Google                            | terminal |
| [3. Connect your AI client](#part-3--connect-your-ai-client) | Add one config entry and restart the client                       | terminal |

### Requirements

- **Node.js 18 or newer** — check with `node --version`; if missing, install from [nodejs.org](https://nodejs.org)
- An [AdMob](https://admob.google.com) account and the Google account that owns it

## Setup

### Part 1 — Google Cloud setup

Why is this needed?\
The AdMob API has no simple API keys — Google requires every program that accesses your data to be registered as an "OAuth app".\
Here you register a personal one that only you will use.\
It's free and needs no billing setup.

1. **Create (or select) a Google Cloud project**: [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate) — any name works; reusing an existing project is fine too.
2. **Enable the AdMob API**: [console.cloud.google.com/apis/library/admob.googleapis.com](https://console.cloud.google.com/apis/library/admob.googleapis.com) → check that your project is selected in the top bar → **Enable**.
3. **Configure the OAuth consent screen**: [console.cloud.google.com/auth/overview](https://console.cloud.google.com/auth/overview) — the first visit opens a short wizard:
   - App name: anything (e.g. `admob-mcp`), and your email as the support/contact email
   - Audience: **External**
   - Finish the wizard — you do **not** need to submit the app for Google's verification
   - Then go to **Audience → Test users → Add users** and add **the Google account that owns your AdMob account**
4. **Create an OAuth client**: [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) → **Create credentials → OAuth client ID**
   - Application type: **Desktop app**
   - After creating it, click **Download JSON** — you'll use this file in Part 2

> [!WARNING]
> While the consent screen is in **Testing** mode, Google expires sign-ins after **7 days**, so you'll need to re-run the sign-in weekly.\
> To stop that, publish the app (**Audience → Publish app**).\
> Publishing for your own use doesn't require Google's verification — you'll just see an "unverified app" warning during sign-in, which is expected.

### Part 2 — Sign in

Move the JSON file you downloaded to where the server looks for it, then run the sign-in command:

```bash
mkdir -p ~/.admob-mcp
mv ~/Downloads/client_secret_*.json ~/.admob-mcp/oauth_client.json

npx admob-mcp-server auth
```

(On Windows, move the file to `C:\Users\\.admob-mcp\oauth_client.json` in Explorer, then run the `npx` command.)

Your browser opens.\
Pick **the Google account that owns your AdMob account** and allow access.\
If you see a **"Google hasn't verified this app"** warning, that's your own app from Part 1 — click "Continue".\
When the terminal prints `Setup complete`, your sign-in is saved to `~/.admob-mcp/token.json` and reused from then on.

By default the sign-in covers every tool, including write tools.\
If you only want reporting access, run `npx admob-mcp-server auth --read-only` instead.

What the `auth` command does:

```mermaid
sequenceDiagram
    autonumber
    participant T as Terminal
    participant S as admob-mcp-server
    participant B as Browser
    participant G as Google

    T->>S: npx admob-mcp-server auth
    S->>S: read ~/.admob-mcp/oauth_client.json
    S->>B: open consent URL (loopback redirect, random port)
    B->>G: sign in & allow scopes
    G-->>S: authorization code → refresh token
    S->>S: save ~/.admob-mcp/token.json (reused for every later call)
```

Advanced: environment variables (headless / CI)

If you already have a refresh token, no files are needed (write tools additionally need the token to cover the `admob.monetization` scope):

```bash
export GOOGLE_CLIENT_ID="....apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="..."
export GOOGLE_REFRESH_TOKEN="..."
```

Advanced: gcloud Application Default Credentials

The same pattern Google's official Analytics/Ads MCP servers use:

```bash
gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/admob.readonly,https://www.googleapis.com/auth/admob.report,https://www.googleapis.com/auth/admob.monetization,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=path/to/oauth_client.json
```

Drop the `admob.monetization` scope if you only want reporting access.

Credential resolution order: **environment variables → `token.json` (from `auth`) → ADC**.

### Part 3 — Connect your AI client

Pick your client below.\
MCP servers are loaded when the client starts, so **restart the client** after adding the config.

**Claude Code**

```bash
claude mcp add admob -- npx -y admob-mcp-server
```

Verify with `claude mcp list` — you should see `admob: ... - ✔ Connected`.

**Claude Desktop** — open **Settings → Developer → Edit Config**, which opens `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), and add:

```json
{
  "mcpServers": {
    "admob": {
      "command": "npx",
      "args": ["-y", "admob-mcp-server"]
    }
  }
}
```

Restart the app; the admob tools appear in the tools menu of the chat input.

**Cursor** — add the same `mcpServers` block to `~/.cursor/mcp.json`, then check **Settings → MCP** shows admob as enabled.

**Gemini CLI** — add the same `mcpServers` block to `~/.gemini/settings.json`, then check with `/mcp` inside the CLI.

> [!TIP]
> If you used the environment-variable sign-in, pass the variables through your client's `env` block (Claude Code: repeat `--env KEY=value` before `--`; JSON configs: add an `"env": { ... }` object next to `"args"`).

## Try it

You don't call tools yourself — just ask in plain language and the assistant picks the right tools.\
Some starters:

- _"What did my apps earn last week?"_
- _"Break down this month's revenue by country and app."_
- _"Which ad format had the highest RPM in the last 30 days?"_
- _"How is my mediation doing? Compare ad sources by observed eCPM."_
- _"List my apps and their ad units."_
- _"Create a rewarded ad unit named 'shop_reward' for my game app."_

Most clients ask for your permission before each tool call, so nothing (especially write operations) runs without your approval.

## Configuration

All configuration is optional — the defaults work for a single AdMob account.

### Environment variables

| Variable                  | Description                                                                                     | Default                               |
| ------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- |
| `ADMOB_ACCOUNT`           | Publisher ID (`pub-XXXXXXXXXXXXXXXX`). Only needed when your login can access multiple accounts | auto-discovered                       |
| `ADMOB_TOOLSETS`          | Comma-separated toolsets to enable                                                              | all                                   |
| `ADMOB_READ_ONLY`         | `true` to skip write tools                                                                      | `false`                               |
| `ADMOB_CREDENTIALS_DIR`   | Directory for `oauth_client.json` / `token.json`                                                | `~/.admob-mcp`                        |
| `ADMOB_OAUTH_CLIENT_FILE` | Path to the OAuth client JSON used by `auth`                                                    | `/oauth_client.json` |
| `GOOGLE_CLIENT_ID`        | OAuth client ID (env sign-in; also used by `auth` instead of the JSON file)                     | —                                     |
| `GOOGLE_CLIENT_SECRET`    | OAuth client secret (env sign-in)                                                               | —                                     |
| `GOOGLE_REFRESH_TOKEN`    | OAuth refresh token (env sign-in)                                                               | —                                     |

### CLI flags

| Flag                   | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `--toolsets `   | Same as `ADMOB_TOOLSETS`, e.g. `--toolsets reports,apps` |
| `--read-only`          | Same as `ADMOB_READ_ONLY=true`                           |
| `--account `   | Same as `ADMOB_ACCOUNT`                                  |
| `--client-file ` | Same as `ADMOB_OAUTH_CLIENT_FILE` (for `auth`)           |

CLI flags take precedence over environment variables.\
Flags go after the command in your client config, e.g. `npx -y admob-mcp-server --read-only`.

## Tools

A "tool" is a function the AI assistant can call on your behalf.\
Tools are grouped into five toolsets; all are enabled by default, and `--read-only` skips the write tools:

| Toolset     | Read tools                                                                           | Write tools (skipped with `--read-only`)                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `accounts`  | `list_accounts`, `get_account`                                                       | —                                                                                                                                              |
| `apps`      | `list_apps`                                                                          | `create_app`                                                                                                                                   |
| `adunits`   | `list_ad_units`                                                                      | `create_ad_unit`                                                                                                                               |
| `reports`   | `generate_network_report`, `generate_mediation_report`, `generate_campaign_report`   | —                                                                                                                                              |
| `mediation` | `list_ad_sources`, `list_adapters`, `list_mediation_groups`, `list_ad_unit_mappings` | `create_mediation_group`, `update_mediation_group`, `create_ad_unit_mapping`, `create_mediation_ab_experiment`, `stop_mediation_ab_experiment` |

Read tools require the `admob.readonly` / `admob.report` scopes; write tools require `admob.monetization` (requested by default during `auth`).

### accounts

| Tool            | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `list_accounts` | List accessible publisher accounts — use to find your `pub-...` ID         |
| `get_account`   | Get account details: publisher ID, reporting currency, reporting time zone |

### apps

| Tool         | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `list_apps`  | List registered apps with app ID, platform, store link, and approval state                    |
| `create_app` | Create an app — link a store listing via `appStoreId`, or register manually via `displayName` |

### adunits

| Tool             | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `list_ad_units`  | List ad units with their IDs, formats, and owning apps                                        |
| `create_ad_unit` | Create an ad unit (`appId`, `displayName`, `adFormat`, optional `adTypes` / `rewardSettings`) |

### reports

All report tools take `startDate` / `endDate` (`YYYY-MM-DD`), `metrics`, and optional `dimensions`, `dimensionFilters`, `sortConditions`, `maxReportRows` (default 1000), `currencyCode`.\
Responses are flat tables; monetary metrics are converted from micros to currency units.

| Tool                        | Description                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `generate_network_report`   | AdMob Network performance: earnings, impressions, clicks, match rate, RPM, ...                       |
| `generate_mediation_report` | Mediation performance across ad sources: earnings, observed eCPM per `AD_SOURCE` / `MEDIATION_GROUP` |
| `generate_campaign_report`  | Cross-promotion campaign stats (last 30 days only): impressions, click

…

## Source & license

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

- **Author:** [ParkSangGwon](https://github.com/ParkSangGwon)
- **Source:** [ParkSangGwon/admob-mcp-server](https://github.com/ParkSangGwon/admob-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-parksanggwon-admob-mcp-server
- Seller: https://agentstack.voostack.com/s/parksanggwon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.