admob-mcp

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:

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.

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

{
  "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:

[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

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.