AdSense MCP
Provides tools to query Google AdSense account data including earnings summaries, top pages, ad unit performance, earnings by ad format, traffic sources, country breakdowns, platform breakdowns, date range comparisons, alerts, and payment history, all read-only.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AdSense MCP How much did I earn this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Description |
| Earnings, page views, impressions, clicks, CTR, RPM for any date range |
| Top pages ranked by earnings, RPM, or impressions |
| CTR, RPM, and earnings per ad unit |
| Revenue breakdown by format (In-page, Vignette, Anchor, Rewarded, etc.) |
| Revenue and RPM by traffic source (Google, Bing, Direct, etc.) |
| Earnings, RPM, and CTR by country |
| Mobile vs desktop vs tablet earnings and traffic split |
| Side-by-side metric comparison with % deltas |
| Active AdSense policy issues and account alerts |
| Payment history sorted by date |
All tools are read-only. No write access to your AdSense account.
Related MCP server: AdSense-MCP-Server
Requirements
Node.js 18+
A Google AdSense account
Claude Desktop
Setup
1. Google Cloud
Go to console.cloud.google.com and create a new project (e.g.
adsense-mcp-personal)Enable the AdSense Management API for the project
Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
Choose Desktop app as the application type
Download the JSON file and save it as
credentials.jsonin the project rootIn 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 build3. Authenticate
Run the one-time OAuth flow:
node auth-setup.jsYour 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.jsonSecurity
credentials.jsonandtoken.jsonare listed in.gitignoreand must never be committedThe OAuth setup server binds to
127.0.0.1only (not exposed to the network)The auth flow uses a CSRF state parameter to prevent code injection
All
limitparameters are capped server-side to prevent quota exhaustionAll 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_pagesrequires 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.jsLicense
MIT
Available Tools
10 toolscompare_date_rangesA
Side-by-side comparison of AdSense metrics across two date ranges with percentage deltas.
Inputs: range_a (required), range_b (required).
get_ad_unit_performanceB
Get performance metrics per ad unit: CTR, RPM, impressions, clicks, and earnings.
Inputs: date_range (required), end_date, start_date, ad_client_id.
get_country_breakdownA
Get earnings breakdown by country — shows which countries generate the most revenue, RPM, CTR, and impressions.
Inputs: date_range (required), limit, end_date, start_date.
get_earnings_by_ad_formatA
Get earnings breakdown by ad format — In-page, Anchor, Vignette, etc. Shows which ad formats generate the most revenue.
Inputs: date_range (required), end_date, start_date.
get_earnings_by_traffic_sourceA
Get earnings breakdown by traffic source — Google, Bing, Facebook, direct, etc. Shows revenue and RPM per source.
Inputs: date_range (required), end_date, start_date.
get_earnings_summaryA
Get AdSense earnings summary for a date range. Returns estimated earnings, page views, impressions, clicks, CTR, and RPM.
Inputs: date_range (required), end_date, start_date.
get_paymentsA
Get AdSense payment history sorted by date descending.
Inputs: limit.
get_platform_breakdownA
Get earnings split by platform — mobile vs desktop vs tablet. Shows earnings share, traffic share, RPM, and CTR per platform.
Inputs: date_range (required), end_date, start_date.
get_top_pagesA
Get top performing pages/URLs ranked by earnings, RPM, or impressions for a date range.
Inputs: date_range (required), limit, sort_by, end_date, +1 more.
list_alertsA
List active AdSense account alerts and policy issues. Returns empty if no alerts.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct reporting dimension or resource—overall summary, pages, ad units, date comparisons, alerts, payments, and breakdowns by country, format, traffic source, and platform. The breakdown tools are clearly separated by their 'by' dimension, so an agent can easily select the right one. Only slight overlap exists between earnings summary and the breakdown tools, but they serve different query purposes.
All tools follow a verb-noun pattern, predominantly `get_*` for data retrieval, with `list_alerts` and `compare_date_ranges` as minor but still verb-noun variations. The names are predictable and consistently describe the resource or breakdown dimension.
Ten tools is a well-scoped catalogue for an AdSense analytics server. Each tool covers a distinct reporting need without redundancy, and the count aligns with typical server sizes for similar domains.
The server covers the core AdSense analytics surface: overall performance, breakthrough dimensions, time comparisons, alerts, and payments. It lacks a tool to list all ad units or sites, but performance metrics per ad unit can be retrieved, and the main read-only workflows are covered. Minor gaps are workable.
Maintenance
Related MCP Connectors
Hosted Google Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Remote MCP server that gives Claude, ChatGPT, Cursor or any MCP client Google search volume, CPC, competition and similar keywords for 50+ countries. Works with no signup at 20 lookups a day; sign in with OAuth or an API key for higher limits, or $4.99 a month for unlimited.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that connects Claude to your Google Sheets for personal finance tracking, analysis, and reporting — all through natural language.2-
- AlicenseAqualityBmaintenanceConnects Google AdSense to MCP clients like Claude and Cursor, enabling earnings summaries, detailed reports, site status checks, and more via natural language.11575 npm5MIT
- AlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol (MCP) server that provides comprehensive Google Analytics 4 (GA4), Google Search Console (GSC), and Google Merchant Center (GMC) integration for Claude Desktop and other MCP clients.Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for Google AdSense management. Create ad units, generate framework-specific ad code, manage earnings reports, and automate ads.txt — all from your AI assistant.1219 npmMIT