AdMob MCP Server

English | 한국어

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 client<br/>Claude Code · Claude Desktop · Cursor · Gemini CLI"]

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

    G["Google AdMob API<br/>v1beta"]

    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	Register a personal "app" so Google lets you access your own data	browser
2. Sign in	Run one command and log in with Google	terminal
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
4. 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\<you>\.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)

<details> <summary><b>Advanced: environment variables (headless / CI)</b></summary>

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="..."

</details>

<details> <summary><b>Advanced: gcloud Application Default Credentials</b></summary>

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.

</details>

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 '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	<credentials dir>/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 <names>	Same as ADMOB_TOOLSETS, e.g. --toolsets reports,apps
--read-only	Same as ADMOB_READ_ONLY=true
--account <pub-id>	Same as ADMOB_ACCOUNT
--client-file <path>	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, clicks, installs, cost

Valid dimensions/metrics per report are exposed as MCP resources (reference documents the assistant can read): admob://reference/network-report-spec, mediation-report-spec, campaign-report-spec.

mediation

Tool	Description
list_ad_sources	List available mediation ad sources (ad networks) and their IDs
list_adapters	List adapters of an ad source, incl. required configuration keys
list_mediation_groups	List mediation groups with targeting and lines (supports filter)
list_ad_unit_mappings	List third-party placements mapped to an ad unit
create_ad_unit_mapping	Map an ad unit to a third-party placement via an adapter
create_mediation_group	Create a mediation group (targeting + mediation lines)
update_mediation_group	Patch a mediation group using an updateMask
create_mediation_ab_experiment	Start an A/B experiment on a mediation group
stop_mediation_ab_experiment	Stop the experiment, choosing the winning variant

Prompts

Prompts are ready-made analysis requests.
Your client surfaces them as slash commands or a prompt picker (e.g. /top_performing_apps in Claude Code).
All take an optional days argument:

Prompt	What it does
top_performing_apps	Ranks your apps by revenue with RPM and match-rate context
revenue_summary	Daily revenue trend with anomaly call-outs
compare_ad_formats	Compares earnings and efficiency across ad formats

Security & privacy

• The server runs entirely on your computer.
  Your data flows only between your machine and Google's API — never through any third-party server.
• Two files are stored locally, both readable only by your user account: ~/.admob-mcp/oauth_client.json (your OAuth app) and ~/.admob-mcp/token.json (your sign-in).
• To sign out: delete ~/.admob-mcp/token.json, and optionally revoke the app's access at myaccount.google.com/permissions.
• Worried about accidental changes?
  Run with --read-only — write tools disappear entirely and the sign-in only requests read scopes.

Troubleshooting

Install & connection

command not found: npx / spawn npx ENOENT

• Cause: Node.js is not installed, or your client can't find it.
• Fix: install Node 18+ from nodejs.org, then restart the client.

The server doesn't appear in the client

• Cause: MCP servers load at client startup, or the server fails to start.
• Fix: restart the client first.
  Then check its MCP status (Claude Code: claude mcp list, Gemini CLI: /mcp), and make sure npx -y admob-mcp-server runs in a terminal without errors.

Sign-in & auth

"No usable Google credentials found"

• Cause: sign-in hasn't been set up yet.
• Fix: follow Part 2 — Sign in.

invalid_grant / "token has been expired or revoked"

• Cause: your sign-in expired.
  With a consent screen in Testing mode this happens every 7 days.
• Fix: re-run npx admob-mcp-server auth.
  To stop it recurring, publish the app (Audience → Publish app).

access_denied during browser sign-in

• Cause: the Google account you picked is not a test user of the consent screen.
• Fix: add it under Audience → Test users, or publish the app.

"The publisher could not be authenticated"

• Cause: the Google account you signed in with has no active AdMob account.
• Fix: re-run npx admob-mcp-server auth and pick the account that owns your AdMob account in the account chooser.

API errors

403 PERMISSION_DENIED

• Cause: the AdMob API isn't enabled, the wrong Google account is signed in, or the write scope is missing.
• Fix: check the following:
  1. The AdMob API is enabled in the same project as your OAuth client
  2. You signed in with the account that owns the AdMob account
  3. For write tools, your token covers admob.monetization — tokens from auth --read-only can't write; re-run npx admob-mcp-server auth

429 RESOURCE_EXHAUSTED

• Cause: AdMob API quota hit (usage limits).
• Fix: retry later, or reduce the request — narrower date range, fewer dimensions.

"Multiple AdMob accounts found"

• Cause: your Google login can access several publisher accounts.
• Fix: set ADMOB_ACCOUNT=pub-... (find IDs with list_accounts).

Development

git clone https://github.com/ParkSangGwon/admob-mcp-server.git
cd admob-mcp-server
npm install
npm test
npm run build

# debug with the MCP Inspector
npm run inspect

To run a local build in a client, point it at the built entry instead of npx: node /path/to/admob-mcp-server/dist/index.js.

Releases: pushing a v* tag runs CI and publishes to npm with provenance (see .github/workflows/release.yml).

Contributing

Issues and pull requests are welcome.
For larger changes, please open an issue first to discuss the direction.
Make sure npm run lint, npm run format:check, and npm test pass.

License

MIT