AdSense MCP

A Model Context Protocol (MCP) server that gives Claude Desktop direct access to your Google AdSense account. Ask plain English questions about your revenue — no dashboard required.

"How much did I earn this week?" "Which pages have the best RPM this month?" "Compare this month vs last month."

Tools

All tools are read-only. No write access to your AdSense account.

Related MCP server: WealthGuard MCP

Requirements

• Node.js 18+

• A Google AdSense account

• Claude Desktop

Setup

1. Google Cloud

1. Go to console.cloud.google.com and create a new project (e.g. adsense-mcp-personal)

2. Enable the AdSense Management API for the project

3. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

4. Choose Desktop app as the application type

5. Download the JSON file and save it as credentials.json in the project root

6. In OAuth consent screen, set the app to Testing mode and add your Gmail as a test user

2. Install

git clone https://github.com/your-username/adsense-mcp.git
cd adsense-mcp
npm install
npm run build

3. Authenticate

Run the one-time OAuth flow:

node auth-setup.js

Your browser will open. Log in with the Google account that owns your AdSense account and click Allow. A token.json file is saved automatically. You never need to repeat this step unless you revoke access.

4. Configure Claude Desktop

Add the following to your Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adsense": {
      "command": "node",
      "args": ["/absolute/path/to/adsense-mcp/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/adsense-mcp with the actual path on your machine.

Restart Claude Desktop. The AdSense tools will be available immediately.

Example Prompts

How much did I earn today?
What were my top 10 pages by RPM last month?
Compare this month vs last month earnings
Which ad format makes the most money?
Which countries have the highest RPM?
Show me mobile vs desktop earnings this month
Where is my traffic coming from and which source pays best?
Do I have any AdSense warnings?
When was my last payment?

Project Structure

adsense-mcp/
├── src/
│   ├── index.ts          # MCP server entry point — tool registry and dispatch
│   ├── auth.ts           # OAuth 2.0 client setup and token refresh
│   ├── adsense.ts        # AdSense API client, date helpers, input validation
│   └── tools/
│       ├── earnings.ts
│       ├── pages.ts
│       ├── adunits.ts
│       ├── adformats.ts
│       ├── trafficsource.ts
│       ├── countries.ts
│       ├── platforms.ts
│       ├── compare.ts
│       ├── alerts.ts
│       └── payments.ts
├── auth-setup.js         # One-time OAuth flow script
├── credentials.json      # From Google Cloud Console — gitignored
├── token.json            # Auto-generated after first login — gitignored
├── package.json
└── tsconfig.json

Security

• credentials.json and token.json are listed in .gitignore and must never be committed

• The OAuth setup server binds to 127.0.0.1 only (not exposed to the network)

• The auth flow uses a CSRF state parameter to prevent code injection

• All limit parameters are capped server-side to prevent quota exhaustion

• All date inputs are validated before reaching the API

• Access tokens are refreshed automatically — no manual intervention needed

Known Limitations

• Read-only. Cannot create or modify ad units.

• ~24h data lag. Today's earnings are always estimates; figures are finalized the following day.

• AdSense only. YouTube and AdMob require separate APIs.

• Single account. Designed for one AdSense account. Multi-account support requires code changes.

• 3-year history limit. The AdSense API does not return data older than 3 years.

• get_top_pages requires AdSense for Content to be enabled on your account.

Development

# Build
npm run build

# Run directly (for testing)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

License

MIT