AdMob MCP Server

A local Model Context Protocol server that connects Claude to the Google AdMob API, giving you a conversational interface to your ad revenue data.

Two ways to use this server:

• Local stdio (Claude Code on one machine): run ./setup.sh and pick L.

• Vercel + Claude.ai Connector (multi-device): click the badge above, then follow docs/VERCEL.md. Or run ./setup.sh and pick V.

Prerequisites

• Node.js 18+

• A Google Cloud project with the AdMob API enabled

• OAuth 2.0 client credentials — Desktop app type for local mode, Web application type for Vercel mode (see docs/VERCEL.md for the Vercel-specific setup).

Setup

1. Get Google OAuth credentials

1. Go to the Google API Console

2. Create or select a project

3. Enable the AdMob API in the API Library

4. Go to Credentials > Create Credentials > OAuth client ID

5. Select Desktop app, name it, and click Create

6. Click Download JSON to download the client secret file

7. Copy the downloaded file into the secrets/ folder in this project

2. Install and configure

cd admob-mcp
./setup.sh

The setup script will:

• Find and rename the Google OAuth JSON to secrets/client_secret.json

• Install dependencies and build

• Open a browser for Google OAuth authorization (token saved to secrets/token.json)

• Register the MCP server with Claude Code

To re-authorize with updated scopes (e.g. after adding another Google MCP):

./setup.sh --reauth

Note: If your Google Cloud project's OAuth consent screen has not been published (i.e. it is still in "Testing" status), you will see an authorization error. To fix this, either publish the app or add your Google account as a test user under OAuth consent screen > Audience in the Google Cloud Console.

Manual configuration

If you prefer not to use setup.sh, add this to your Claude Code MCP config:

{
  "mcpServers": {
    "admob": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/admob-mcp/dist/src/index.js"],
      "env": {
        "ADMOB_CREDENTIALS_PATH": "/absolute/path/to/admob-mcp/secrets/client_secret.json"
      }
    }
  }
}

Connector setup (Vercel)

Use this if you want the AdMob tools available in Claude.ai on every device, not just Claude Code on your laptop.

1. Fork the repo.

2. Click Deploy with Vercel above.

3. Provision Upstash Redis in the Vercel Storage tab — it auto-injects the KV_* env vars our code uses. (Vercel deprecated standalone "Vercel KV"; Upstash is the same backend.)

4. Create a Google Cloud OAuth client (Web app). Authorized redirect URI = https://<your-deploy>.vercel.app/api/oauth/callback.

5. Set env vars in Vercel: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, OAUTH_REDIRECT_URI, CONNECTOR_TOKEN (generate with openssl rand -hex 32). Watch for stray whitespace.

6. Visit https://<your-deploy>.vercel.app/api/setup, paste CONNECTOR_TOKEN, click Authorize, and complete Google sign-in. This authorizes the server to read AdMob data on your behalf.

7. In Claude.ai → Settings → Connectors → Add custom connector: paste https://<your-deploy>.vercel.app/api/mcp as the URL, leave OAuth Client ID and Secret blank, click Add, then click Connect. A browser tab opens at /oauth/authorize — paste the same CONNECTOR_TOKEN once. Claude.ai handles the rest.

Two OAuth flows are gated by the same CONNECTOR_TOKEN: Google ↔ server (step 6) and Claude.ai ↔ server (step 7). Full walkthrough including troubleshooting: docs/VERCEL.md.

Usage

Just ask Claude a question about your AdMob data in natural language. On first use, Claude will automatically call list_accounts to discover your AdMob accounts and ask which one you want to work with. After that, it will use the appropriate tools to answer your questions.

Tools

Core API tools

Reporting tools

Revenue optimization tools

Project structure

• src/index.ts — stdio entry point (Claude Code).

• src/tools.ts — all 36 tool definitions; registerTools(server, getClient).

• src/auth.ts — Google OAuth helpers (getAuthenticatedClient, authorizeViaLocalServer).

• src/token-store.ts — TokenStore interface + FileTokenStore (local) + KvTokenStore (Vercel KV).

• src/oauth-store.ts — KV-backed storage for the connector OAuth flow (auth codes + access tokens).

• src/http-auth.ts — Timing-safe bearer check for HTTP endpoints (sync against CONNECTOR_TOKEN, async against KV-issued access tokens).

• src/admob-client.ts, src/helpers.ts — REST client and report-formatting utilities.

• api/mcp.ts — Vercel function: HTTP MCP endpoint (Streamable HTTP, bearer-gated, emits WWW-Authenticate on 401).

• api/setup.ts — Vercel function: form that initiates the Google ↔ server OAuth flow.

• api/oauth/callback.ts — Vercel function: Google's redirect URI; stores tokens in KV.

• api/oauth/authorize.ts, api/oauth/token.ts, api/oauth/register.ts — Vercel functions implementing the Claude.ai ↔ server OAuth 2.1 flow with PKCE and Dynamic Client Registration.

• api/well-known/oauth-authorization-server.ts, api/well-known/oauth-protected-resource.ts — RFC 8414 / RFC 9728 metadata so Claude.ai can discover the OAuth endpoints.

• setup.sh — Interactive setup script ([L]ocal / [V]ercel / [B]oth).

• docs/VERCEL.md — Forker deployment guide.

• AGENTS.md — Canonical project notes (CLAUDE.md is a symlink to it).

Development

npm run build     # Compile TypeScript
npm run start     # Run the server directly (stdio)