Admob Mcp Server

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) server for the Google AdMob API.\ It works with Claude Code, Claude Desktop, Cursor, Gemini CLI, and any other MCP-capable AI client.

Architecture

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
• An AdMob 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 — any name works; reusing an existing project is fine too.
2. Enable the AdMob API: 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 — 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

1. Create an OAuth client: 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:

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:

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

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:

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

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:

{
  "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 'shopreward' 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
• Source: ParkSangGwon/admob-mcp-server
• License: MIT

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