AdSense Server

Google AdSense MCP Server — Connect Google AdSense to Claude, Cursor, and other MCP clients.

npm version npm downloads License: MIT CI

Features

• 📊 Earnings Summary — Quick overview of today, yesterday, last 7 days, and monthly earnings
• 📈 Detailed Reports — Generate reports with dimensions (date, site, country, ad unit) and metrics
• 🔄 Period Comparison — Compare performance between time periods
• 🌐 Site Status — Check approval status for all your sites
• ⚠️ Alerts & Policy Issues — Monitor account health and catch violations early
• 💰 Payment History — View payment history and pending earnings
• 📦 Ad Units — List ad units and get embed codes
• 📤 CSV Export — Export reports for further analysis
• 💾 Caching — SQLite cache for faster repeated queries
• 🔐 Secure — OAuth tokens stored in OS keychain, read-only scope

Quick Start

# Install globally
npm install -g @appsyogi/adsense-mcp-server

# Set up OAuth credentials
adsense-mcp init

# Verify setup
adsense-mcp doctor

# Start the server (for MCP clients)
adsense-mcp run

Prerequisites

1. Create Google Cloud OAuth Credentials

You need to create your own OAuth credentials in Google Cloud Console:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the AdSense Management API:
   • Go to "APIs & Services" → "Library"
   • Search for "AdSense Management API"
   • Click "Enable"
4. Create OAuth credentials:
   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "OAuth client ID"
   • Choose "Desktop application"
   • Name it (e.g., "AdSense-MCP")
   • Click "Create"
5. Copy the Client ID and Client Secret
6. Add test users (required while app is in testing mode):
   • Go to "APIs & Services" → "OAuth consent screen"
   • Scroll to "Test users" section
   • Click "Add users"
   • Add the Google account email(s) you'll use to authenticate
   • Click "Save"

Note: While your app's publishing status is "Testing", only test users can authenticate. You can add up to 100 test users.

2. Configure AdSense-MCP

Run the init command and enter your credentials:

adsense-mcp init

This will:

• Prompt for your Client ID and Client Secret
• Open a browser for Google authentication
• Store your refresh token securely in the OS keychain

Installation

npx @appsyogi/adsense-mcp-server init

Quick Start

1. Initialize (OAuth Setup)

npx adsense-mcp init

This will:

• Open your browser for Google sign-in
• Request read-only access to your AdSense data
• Let you select your default account (if you have multiple)
• Store credentials securely

2. Verify Setup

npx adsense-mcp doctor

3. Add to Your MCP Client

VS Code Copilot (~/.vscode/mcp.json)

{
    "servers": {
        "adsense": {
            "command": "npx",
            "args": ["@appsyogi/adsense-mcp-server", "run"],
            "type": "stdio"
        }
    }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
    "mcpServers": {
        "adsense": {
            "command": "npx",
            "args": ["@appsyogi/adsense-mcp-server", "run"]
        }
    }
}

Available Tools

Tool	Description
adsense_list_accounts	List all AdSense accounts you have access to
adsense_earnings_summary	Quick earnings overview (today, yesterday, last 7 days, this month)
adsense_generate_report	Generate detailed reports with custom dimensions and metrics
adsense_compare_periods	Compare performance between two time periods
adsense_list_sites	List all sites with their approval status
adsense_list_alerts	Get account alerts and warnings
adsense_list_policy_issues	Check for policy violations
adsense_list_payments	View payment history and pending earnings
adsense_list_ad_units	List all ad units
adsense_get_ad_code	Get HTML embed code for an ad unit
adsense_export_csv	Export report data as CSV

Example Conversations

Check Earnings

You: How's my AdSense doing today?

Claude: 📊 **AdSense Earnings Summary**

| Period | Earnings | Impressions | Clicks | CTR |
|--------|----------|-------------|--------|-----|
| Today | $8.45 | 3,200 | 28 | 0.88% |
| Yesterday | $15.67 | 6,200 | 52 | 0.84% |
| Last 7 Days | $98.45 | 42,000 | 380 | 0.90% |
| This Month | $345.67 | 150,000 | 1,350 | 0.90% |

You're tracking 16% ahead of last month at this point! 🎉

Check Site Status

You: Is my new site approved yet?

Claude: 📋 **Site Status**

| Site | Status | Notes |
|------|--------|-------|
| example.com | ✅ READY | Ads serving |
| blog.example.com | ⏳ GETTING_READY | Under review |
| newsite.com | ⚠️ NEEDS_ATTENTION | Insufficient content |

Generate Report

You: Show me earnings by country for last week

Claude: [Generates report with COUNTRY_NAME dimension]

CLI Commands

adsense-mcp init

Set up OAuth authentication and select default account.

# Interactive setup
npx adsense-mcp init

# Set specific default account
npx adsense-mcp init --account pub-1234567890123456

# Use service account (advanced)
npx adsense-mcp init --service-account /path/to/key.json

adsense-mcp doctor

Verify your setup and check account health.

npx adsense-mcp doctor

adsense-mcp run

Start the MCP server (typically called by your MCP client).

# Use default account
npx adsense-mcp run

# Use specific account
npx adsense-mcp run --account pub-9876543210987654

# Verbose logging
npx adsense-mcp run --verbose

Multi-Account Support

If you have multiple AdSense accounts, you can:

1. Select default during init
2. Override with --account flag
3. Use adsense_list_accounts tool to see all accounts
4. Pass accountId parameter to any tool

Data Storage

All data is stored locally in ~/.config/adsense-mcp/:

• config.json - Default account and settings
• tokens.json - OAuth refresh token (encrypted)
• cache.sqlite - Report cache for faster responses

Security

• Read-only access - This server only requests adsense.readonly scope
• Secure token storage - Tokens are encrypted using OS keychain (via keytar)
• Local only - All data stays on your machine
• No telemetry - We don't collect any usage data

Rate Limits

The AdSense API has strict rate limits (100 requests/minute). This server:

• Caches responses intelligently (5min-24hr based on data type)
• Implements exponential backoff for retries
• Tracks request rates to avoid hitting limits

Troubleshooting

"No tokens found" error

Run npx adsense-mcp init to set up authentication.

"Rate limit exceeded" error

Wait a minute and try again. The server will automatically retry with backoff.

"Account not found" error

Make sure you've selected a valid account during setup. Run npx adsense-mcp doctor to see available accounts.

Development

# Clone the repo
git clone https://github.com/AppsYogi-com/adsense-mcp-server.git
cd adsense-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Test locally
node dist/cli/index.js doctor

License

MIT

Contributing

Contributions are welcome! Please open an issue or PR.

Credits

Built with:

• @modelcontextprotocol/sdk
• googleapis
• commander
• better-sqlite3
• keytar