AdSense-MCP-Server
Connects to Google AdSense API to fetch earnings summaries, detailed reports with dimensions and metrics, period comparisons, site approval status, alerts and policy issues, payment history, ad units with embed codes, and CSV export, with caching for faster repeated queries.
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-Server Show me today's earnings summary."
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-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 — Every AdSense v2 dimension and metric, with sorting and filters
🔄 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 — Read-only scope, tokens in your OS keychain, signed npm releases with provenance
Related MCP server: GA4 MCP Server
Quick Start
npm install -g @appsyogi/adsense-mcp-server
adsense-mcp init # sign in with Google (opens your browser)
adsense-mcp doctor # check everything worksThen add the server to your MCP client. The first time, you also need a Google Cloud OAuth client.
Requirements
Node.js 18 or newer. Node.js 22+ is recommended, since 18 and 20 have reached end-of-life and v0.3.0 will require 22.
A Google account with access to an AdSense account
A Google Cloud project, used only to create your own OAuth client (free)
Setup
1. Create a Google Cloud OAuth client (one-time)
This server signs in with your own OAuth client, so your data never passes through a third party.
Open the Google Cloud Console and create or select a project.
Enable the AdSense Management API: go to APIs & Services → Library, search for "AdSense Management API", and click Enable.
Configure the consent screen: go to APIs & Services → OAuth consent screen (shown as Google Auth Platform in newer consoles).
Choose an app name and set Audience to External.
Under Test users, add the Google account that owns your AdSense account.
Create the OAuth client: go to APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Desktop app. This is required, because only Desktop app clients accept the local
127.0.0.1redirect thatinituses.Copy the Client ID (ends in
.apps.googleusercontent.com) and the Client Secret (usually starts withGOCSPX-).
While the app's publishing status is Testing, only test users can sign in, and Google expires sign-ins after 7 days. See invalid_grant if you'd rather not sign in again every week.
2. Install
npm install -g @appsyogi/adsense-mcp-serverThis installs the adsense-mcp command. You can also run it without installing, using npx @appsyogi/adsense-mcp-server <command>.
3. Sign in
adsense-mcp initPaste your Client ID and Client Secret when asked. If you swap them by mistake,
initnotices and fixes the order.Your browser opens Google's sign-in page. Choose the account that owns your AdSense account and approve read-only access.
The browser shows "AdSense MCP is authorized", and the terminal prints "✅ Authentication successful!"
How it works: init starts a temporary local server on http://127.0.0.1:<random port> and Google redirects back to it, using PKCE and a state check. You never copy or paste a code. The link is valid for 5 minutes, and each run creates a new link.
If the browser doesn't open, or you're on a different machine from the terminal, copy the printed https://accounts.google.com/... link into a browser yourself.
4. Verify
adsense-mcp doctor✅ Config: OAuth client 123456789012…abcd (saved 11/12/2026, 1:18:35 PM)
✅ Tokens: Sign-in saved (with refresh token)
✅ AdSense API: Found 1 account(s)
✅ Cache: Not yet created (will be created on first use)
✅ All checks passed! Server is ready to use.When everything passes, doctor also prints a ready-to-paste MCP config with the exact paths for your machine.
5. Add to your MCP client
Claude Desktop
Quit Claude Desktop before editing its config: use ⌘Q on macOS, not just closing the window. While it's running, Claude Desktop keeps its own copy of this file and writes it back, so edits made with the app open can silently disappear. It also reads
mcpServersonly at startup.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows. Add an adsense entry under mcpServers, keeping any servers already there.
Recommended: full paths. Desktop apps don't load your shell's PATH, so node and npx from nvm, fnm or asdf often can't be found. This server also contains native modules built for one specific Node.js version.
{
"mcpServers": {
"adsense": {
"command": "/Users/you/.nvm/versions/node/v24.11.0/bin/node",
"args": [
"/Users/you/.nvm/versions/node/v24.11.0/lib/node_modules/@appsyogi/adsense-mcp-server/dist/cli/index.js",
"run"
]
}
}
}which node and npm root -g show the right paths, or copy the config adsense-mcp doctor prints.
Alternative: npx. This works if npx is on the PATH that Claude Desktop sees:
{
"mcpServers": {
"adsense": {
"command": "npx",
"args": ["-y", "@appsyogi/adsense-mcp-server", "run"]
}
}
}Save the file, open Claude Desktop, and ask "List my AdSense accounts".
Claude Code
claude mcp add adsense -- adsense-mcp runVS Code (.vscode/mcp.json)
{
"servers": {
"adsense": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@appsyogi/adsense-mcp-server", "run"]
}
}
}Available Tools
Tool | Description |
| List all AdSense accounts you have access to |
| Quick earnings overview (today, yesterday, last 7 days, this month, last month) |
| Detailed reports with custom dimensions, metrics, sorting and filters |
| Compare performance between two time periods |
| List all sites with their approval status |
| Get account alerts and warnings |
| Check for policy violations |
| View payment history and pending earnings |
| List all ad units |
| Get HTML embed code for an ad unit |
| Export report data as CSV |
Report options
adsense_generate_report and adsense_export_csv accept:
dimensions/metrics: any AdSense v2 dimension (56) or metric (36), such asCOUNTRY_NAME,PLATFORM_TYPE_CODE,CUSTOM_CHANNEL_NAME,ESTIMATED_EARNINGSorPAGE_VIEWS_RPM. Names are case-insensitive and can be comma-separated.orderBy(adsense_generate_reportonly): a dimension or metric, prefixed with-for descending or+for ascending, e.g.-ESTIMATED_EARNINGS.filters:DIMENSION==valuefor an exact match orDIMENSION=@valuefor "contains", e.g.COUNTRY_CODE==US.Separate entries are combined with AND.
Use a comma inside one entry for OR, e.g.
COUNTRY_CODE==US,COUNTRY_CODE==GB.Date dimensions can't be filtered; use the date range instead.
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 last week's top 5 countries by earnings, mobile only
Claude: [Runs adsense_generate_report with dimensions COUNTRY_NAME,
orderBy -ESTIMATED_EARNINGS, filters PLATFORM_TYPE_CODE==HighEndMobile, limit 5]CLI Commands
adsense-mcp init
Sign in with your Google Cloud OAuth client and save your tokens.
# Interactive: prompts for Client ID and Secret, then opens the browser
adsense-mcp init
# Non-interactive credentials
adsense-mcp init --client-id <id>.apps.googleusercontent.com --client-secret <secret>
# Use a fixed port for the OAuth redirect (default: random free port)
adsense-mcp init --port 8085
# Use a service account (AdSense for Platforms only, see note below)
adsense-mcp init --service-account /path/to/key.jsonService accounts: The AdSense Management API doesn't support service accounts for regular AdSense accounts. They only work for AdSense for Platforms accounts, after Google adds the service account to your AdSense account through your account manager. Everyone else should use OAuth (plain
init). Runninginit --service-accountreplaces any existing OAuth setup.
adsense-mcp doctor
Checks your saved config and tokens, calls the AdSense API, and explains how to fix anything that fails. It also warns if a recent init didn't finish signing in.
adsense-mcp doctoradsense-mcp run
Starts the MCP server over stdio. Your MCP client normally runs this for you.
# Use the default account (the first one your Google account can access)
adsense-mcp run
# Use a specific account
adsense-mcp run --account pub-9876543210987654Multiple Accounts
By default the server uses the first AdSense account your Google account can access. To use another one:
Per request: pass
accountIdto any tool, or just ask Claude for a specific account. Useadsense_list_accountsto see the IDs.As the default: add
"--account", "pub-…"to theargsin your MCP config, or set theADSENSE_ACCOUNT_IDenvironment variable.
Updating
npm install -g @appsyogi/adsense-mcp-server@latest
adsense-mcp doctorIf you're upgrading from 0.1.x, run adsense-mcp init once more. Google blocked the sign-in method that 0.1.x used.
Data Storage
Everything stays on your machine:
What | Where |
Config ( | macOS: |
OAuth tokens | Your OS keychain (via keytar). If no keychain is available, |
OAuth client from your last |
|
Security
Read-only access: only the
adsense.readonlyscope is requested, so nothing in your account can be changed.Your own OAuth client: sign-in happens directly between your machine and Google.
Secure token storage: tokens are kept in your OS keychain whenever one is available.
Signed releases: packages are published from GitHub Actions through npm trusted publishing, with provenance. Check them with
npm audit signatures.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
Start with adsense-mcp doctor. Most failures come with a suggested fix.
"The out-of-band (OOB) flow has been blocked"
You're on 0.1.x, which used a sign-in method Google has shut down. Update, then run adsense-mcp init again.
"Error 401: invalid_client" / "The OAuth client was not found"
The Client ID is wrong, the client was deleted, or the ID and secret were swapped. Copy both again from APIs & Services → Credentials and re-run init.
"Error 400: redirect_uri_mismatch"
Your OAuth client isn't of type Desktop app. Create a Desktop app client. If you have to use a Web application client, add http://127.0.0.1:8085 as an authorized redirect URI and run adsense-mcp init --port 8085.
"Access blocked" / "Error 403: access_denied"
The Google account you signed in with isn't a test user. Add it under OAuth consent screen → Test users.
Google shows "400. That's an error … malformed"
This usually comes from the browser's Google session, not this tool.
Copy the link from the terminal into a private window, or a browser profile signed in only to your AdSense account.
Use the link from the latest
initrun; older links stop working.
"Timed out waiting for authorization"
Sign-in wasn't completed within 5 minutes. Run adsense-mcp init again.
invalid_grant after a week
Your sign-in expired or was revoked. While the consent screen is in Testing, Google expires sign-ins after 7 days, so run adsense-mcp init again. To avoid this, set the app's publishing status to In production. Google then shows an "unverified app" warning during sign-in, which is fine for personal use.
"was compiled against a different Node.js version" (NODE_MODULE_VERSION)
The native modules were built for a different Node.js version than the one running the server. Fix it in either of two ways:
Reinstall with the Node.js version your MCP client uses:
npm install -g @appsyogi/adsense-mcp-server.Use full paths in your MCP config, as shown in Claude Desktop.
The server doesn't show up in Claude Desktop
Check the log:
~/Library/Logs/Claude/mcp-server-adsense.logon macOS, or%APPDATA%\Claude\logs\on Windows.spawn node ENOENTorspawn npx ENOENTmeans Claude Desktop can't find Node.js. Use full paths.Your
adsenseentry is gone from the config: Claude Desktop overwrote the file while it was running. Quit it with ⌘Q, make sure it's no longer running, add the entry again, then reopen it.The entry is there but no tools appear: Claude Desktop only loads servers at startup, so quit it completely (⌘Q) and reopen it.
"No AdSense accounts found" / "Account not found"
Sign in with the Google account that has access to AdSense. Run adsense-mcp doctor to see which accounts are found.
"Rate limit exceeded"
Wait a minute and try again. The server retries automatically with backoff.
Development
git clone https://github.com/AppsYogi-com/adsense-mcp-server.git
cd adsense-mcp-server
npm install
npm run typecheck
npm run build
node dist/cli/index.js doctorUse npm run dev to rebuild on every change.
Contributing
Contributions are welcome! Open an issue or PR. Planned work is tracked in the v0.3.0 milestone.
License
MIT
Credits
Built with:
Available Tools
11 toolsadsense_compare_periodsC
Compare AdSense performance between two time periods
Inputs: period1End (required), period2End (required), period1Start (required), period2Start (required), +2 more.
adsense_earnings_summaryB
Get a quick earnings summary (today, yesterday, last 7 days, this month, last month)
Inputs: accountId.
adsense_export_csvC
Export AdSense report data as CSV format
Inputs: endDate (required), startDate (required), filters, metrics, +2 more.
adsense_generate_reportB
Generate a detailed AdSense performance report with custom dimensions and metrics
Inputs: limit, endDate, filters, metrics, +4 more.
adsense_get_ad_codeB
Get the HTML embed code for an ad unit
Inputs: adUnitId (required), adClientId (required), accountId.
adsense_list_accountsA
List all AdSense accounts you have access to
Inputs: no named parameters.
adsense_list_ad_unitsC
List all ad units across your ad clients
Inputs: accountId.
adsense_list_alertsC
List AdSense account alerts and warnings (INFO, WARNING, SEVERE)
Inputs: accountId.
adsense_list_paymentsC
List payment history and pending earnings
Inputs: accountId.
adsense_list_policy_issuesA
List policy issues and violations affecting your account (WARNED, AD_SERVING_RESTRICTED, AD_SERVING_DISABLED)
Inputs: accountId.
adsense_list_sitesA
List all sites and their AdSense approval status (READY, GETTING_READY, NEEDS_ATTENTION, REQUIRES_REVIEW)
Inputs: accountId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Tools target largely distinct resources and actions: account listing, earnings summary, detailed reports, period comparison, sites, alerts, policy issues, payments, ad units, ad code, and CSV export. Minor overlap exists between generate_report and export_csv, and earnings_summary versus generate_report, but descriptions make the intended use clear.
All tools use the adsense_ prefix and snake_case, with most following a predictable verb_noun pattern such as list_accounts, generate_report, and compare_periods. The main minor deviation is earnings_summary, which is noun-based rather than verb-based, but it remains readable and consistent with the rest.
11 tools is well-scoped for an AdSense reporting and account-monitoring server, with each tool covering a meaningful area. The set avoids excessive fragmentation or redundancy while remaining broad enough for common workflows.
The surface covers core read/reporting workflows: accounts, earnings, reports, comparisons, sites, alerts, policy issues, payments, ad units, embed code, and CSV export. Write or management operations are absent, but for an AdSense reporting integration this is a minor gap rather than a major dead end.
Maintenance
Related MCP Connectors
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
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.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude to the Google AdMob API to provide a conversational interface for managing and analyzing ad revenue data. It enables users to generate custom network reports, track performance trends, and diagnose revenue fluctuations using natural language.6MIT
- AlicenseAqualityCmaintenanceConnects MCP clients like Claude Desktop to Google Analytics 4 Data API, enabling natural language queries for reports, top pages, traffic sources, conversions, realtime users, and period comparisons.770 PyPIMIT
- AlicenseAqualityDmaintenanceA 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.1019 npmMIT
- 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