Adsense MCP Server
A CLI-installable MCP (Model Context Protocol) server that enables Claude, Cursor, and other AI assistants to interact with your Google AdSense account.
Ask AI about Adsense MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Adsense MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AdSense-MCP-Server
Google AdSense MCP Server β Connect Google AdSense to Claude, Cursor, and other MCP clients.
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:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the AdSense Management API:
- Go to "APIs & Services" β "Library"
- Search for "AdSense Management API"
- Click "Enable"
- 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"
- Copy the Client ID and Client Secret
- 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:
- Select default during
init - Override with
--accountflag - Use
adsense_list_accountstool to see all accounts - Pass
accountIdparameter to any tool
Data Storage
All data is stored locally in ~/.config/adsense-mcp/:
config.json- Default account and settingstokens.json- OAuth refresh token (encrypted)cache.sqlite- Report cache for faster responses
Security
- Read-only access - This server only requests
adsense.readonlyscope - 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:
