Skip to main content
Glama
AdSense MCP

AdSense MCP

by vishmathpati

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

get_earnings_summary

Earnings, page views, impressions, clicks, CTR, RPM for any date range

get_top_pages

Top pages ranked by earnings, RPM, or impressions

get_ad_unit_performance

CTR, RPM, and earnings per ad unit

get_earnings_by_ad_format

Revenue breakdown by format (In-page, Vignette, Anchor, Rewarded, etc.)

get_earnings_by_traffic_source

Revenue and RPM by traffic source (Google, Bing, Direct, etc.)

get_country_breakdown

Earnings, RPM, and CTR by country

get_platform_breakdown

Mobile vs desktop vs tablet earnings and traffic split

compare_date_ranges

Side-by-side metric comparison with % deltas

list_alerts

Active AdSense policy issues and account alerts

get_payments

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

  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

Available Tools

10 tools
compare_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

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that connects Claude to your Google Sheets for personal finance tracking, analysis, and reporting — all through natural language.
      2
      -
    • A
      license
      A
      quality
      B
      maintenance
      Connects Google AdSense to MCP clients like Claude and Cursor, enabling earnings summaries, detailed reports, site status checks, and more via natural language.
      11
      575 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      12
      19 npm
      MIT