adsense-mcp
This server provides read-only access to Google AdSense data via MCP, covering accounts, payments, alerts, policy issues, sites, inventory, ad codes, and reports.
Account management: List, get, and list child accounts; view payments, alerts, ad blocking recovery tags, policy issues, and sites.
Inventory inspection: List/get ad clients, ad units, custom channels, URL channels, and their linked resources; retrieve ad codes for ad clients and ad units.
Reporting: List and get saved reports, generate saved reports, and create ad-hoc reports with metrics, dimensions, filters, date ranges, sorting, and pagination.
Authentication: Uses read-only OAuth scope; supports access token or client ID/secret/refresh token; works with MCP clients like Claude Desktop and Codex.
Data retrieval: Returns structured JSON; paginated list tools support pageSize/pageToken.
Security: No write operations; credentials are kept private and not exposed.
Provides tools to interact with Google AdSense, allowing you to list accounts, get account details, and generate performance reports using the AdSense Management API.
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 Generate a report of estimated earnings by date for the last 30 days."
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
An MCP server providing read-only access to the AdSense Management API v2: accounts, payments, alerts, policy issues, sites, inventory, ad code, and saved or ad-hoc reports.
The server uses the read-only https://www.googleapis.com/auth/adsense.readonly OAuth scope. It does not write to an AdSense account.
Install
Once published, run it from an MCP client with npx -y @sirmacke/adsense-mcp. Configure either ADSENSE_ACCESS_TOKEN, or all three of ADSENSE_CLIENT_ID, ADSENSE_CLIENT_SECRET, and ADSENSE_REFRESH_TOKEN.
Related MCP server: google-ads-mcp
Security
OAuth access tokens, refresh tokens, and client secrets are credentials. Keep them out of this repository, issue trackers, shell history, and MCP configuration that is shared with others. If one is exposed, revoke it in Google Cloud immediately; see SECURITY.md.
Setup
In Google Cloud, enable AdSense Management API and create an OAuth Desktop client.
Obtain a refresh token granted the
https://www.googleapis.com/auth/adsense.readonlyscope. Keep it secret.Copy
.env.exampleto your secure environment configuration and populate eitherADSENSE_ACCESS_TOKENor the OAuth client ID, secret, and refresh token.Install and build:
npm install
npm run buildOne-time OAuth authorization (without gcloud)
Download the OAuth Desktop client JSON from Google Cloud, then run:
$env:ADSENSE_OAUTH_CLIENT_FILE = "C:\secure\adsense-client.json"
$env:ADSENSE_TOKEN_FILE = "C:\secure\adsense-oauth.json"
npm run authorizeThe command opens the Google consent screen on a localhost callback and saves the client ID, client secret, and refresh token only in the private token file. Copy those values to the ADSENSE_CLIENT_ID, ADSENSE_CLIENT_SECRET, and ADSENSE_REFRESH_TOKEN fields of the MCP configuration. Do not leave an External consent screen in Testing: its refresh tokens expire after seven days.
Claude Desktop
Current Claude Desktop builds use extensions. Run npm run package, then install build/adsense-mcp.mcpb from Settings → Extensions → Advanced settings → Install extension. It securely prompts for the OAuth values. On installations that support classic configuration, add this instead:
{
"mcpServers": {
"adsense": {
"command": "node",
"args": ["/absolute/path/to/adsense-mcp/dist/index.js"],
"env": {
"ADSENSE_CLIENT_ID": "...",
"ADSENSE_CLIENT_SECRET": "...",
"ADSENSE_REFRESH_TOKEN": "..."
}
}
}
}Codex
Add the equivalent server definition to your Codex MCP configuration, using the same command, arguments, and environment variables. The server uses the standard MCP stdio transport and works in both clients.
Tools
Accounts and account status
adsense_list_accountsadsense_get_accountadsense_list_child_accountsadsense_list_paymentsadsense_list_alertsadsense_get_ad_blocking_recovery_tagadsense_list_policy_issuesadsense_get_policy_issueadsense_list_sitesadsense_get_site
Inventory
adsense_list_ad_clientsadsense_get_ad_clientadsense_get_ad_client_ad_codeadsense_list_ad_unitsadsense_get_ad_unitadsense_get_ad_unit_ad_codeadsense_list_linked_custom_channelsadsense_list_url_channelsadsense_get_url_channeladsense_list_custom_channelsadsense_get_custom_channeladsense_list_linked_ad_units
Reports
adsense_list_saved_reportsadsense_get_saved_reportadsense_generate_saved_reportadsense_generate_report
Account-level tools discover the configured or first accessible account when account is omitted. Paginated list tools accept pageSize and pageToken; pass a returned nextPageToken to continue. Resource-specific tools accept the canonical names returned by their corresponding list tools.
adsense_list_payments returns paid and unpaid earnings, including the formatted amount and, for paid earnings, the credited date. The AdSense API does not expose bank or payment-method details.
Example report request: metrics: ["ESTIMATED_EARNINGS", "PAGE_VIEWS", "CLICKS"], dimensions: ["DATE", "COUNTRY_NAME"], dateRange: "LAST_7_DAYS", orderBy: ["-ESTIMATED_EARNINGS"].
The server returns structured JSON. The API's duplicate CSV report methods are intentionally omitted because agents can transform the structured response when CSV is needed.
Verify
npm test
npm run buildLive verification also requires the OAuth values above and an AdSense account. Every exposed endpoint accepts the AdSense read-only OAuth scope.
Releasing
Releases are published to both npm and the official MCP Registry. The registry stores discovery metadata from server.json; the installable server itself is distributed through npm.
Update the version consistently in
package.json,package-lock.json,server.json(including its npm package entry),mcpb/manifest.json, and the MCP server version insrc/index.ts.Run
npm testandnpm pack --dry-runto verify the build and published package contents.Commit and push the release to GitHub.
Publish the public scoped package with
npm publish --access public.Authenticate when necessary with
mcp-publisher login github, then runmcp-publisher publishto publish the matchingserver.jsonversion.
Publish npm before the MCP Registry because registry validation requires the referenced public package version to exist. Published versions are immutable, so corrections require a new version.
License
Available Tools
3 toolsadsense_generate_reportA
Extract any ad-hoc AdSense report. Supply API v2 dimensions, metrics, filters, dates, sorting, and other report parameters. Account is discovered automatically when omitted.
Inputs: metrics (required), limit, account, endDate, +8 more.
adsense_get_accountA
Get one AdSense account by resource name, e.g. accounts/pub-123.
Inputs: account (required).
adsense_list_accountsA
List AdSense accounts available to the authenticated user.
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 3 tools
Each tool targets a distinct operation: listing accounts, retrieving a specific account, and generating reports. There is no overlap between these actions, and the report tool even auto-discovers the account, reducing ambiguity.
All tool names follow a consistent verb_noun pattern with the 'adsense_' prefix (list_accounts, get_account, generate_report). This makes the naming predictable and easy to navigate.
With 3 tools, the server is on the lower end of the ideal range, but it covers the core AdSense operations: account listing, account retrieval, and report generation. The count feels minimal yet sufficient for a focused server, though slightly thin.
The surface covers essential account and reporting operations, but lacks other common AdSense resources like ad units, sites, or alerts. This might be a notable gap for agents needing broader management capabilities, though it may be acceptable for a report-focused server.
Maintenance
Related MCP Connectors
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Query selected Google and Bing analytics, search, and advertising reports through MCP.
Related MCP Servers
- 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
- AlicenseNot gradedqualityDmaintenanceMCP server for Google Ads campaign reporting and management via Claude, enabling GAQL queries, performance metrics, and campaign modifications.58 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for querying Google Analytics accounts, properties, reports, and realtime data using the Data API and Admin API.1Apache 2.0
- AlicenseNot gradedqualityFmaintenanceMCP server that provides tools to interact with Google Analytics APIs, enabling account and property retrieval, report running, and custom dimension/metrics access.Apache 2.0