Skip to main content
Glama
adsense-mcp

adsense-mcp

by SirMacke

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

  1. In Google Cloud, enable AdSense Management API and create an OAuth Desktop client.

  2. Obtain a refresh token granted the https://www.googleapis.com/auth/adsense.readonly scope. Keep it secret.

  3. Copy .env.example to your secure environment configuration and populate either ADSENSE_ACCESS_TOKEN or the OAuth client ID, secret, and refresh token.

  4. Install and build:

npm install
npm run build

One-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 authorize

The 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_accounts

  • adsense_get_account

  • adsense_list_child_accounts

  • adsense_list_payments

  • adsense_list_alerts

  • adsense_get_ad_blocking_recovery_tag

  • adsense_list_policy_issues

  • adsense_get_policy_issue

  • adsense_list_sites

  • adsense_get_site

Inventory

  • adsense_list_ad_clients

  • adsense_get_ad_client

  • adsense_get_ad_client_ad_code

  • adsense_list_ad_units

  • adsense_get_ad_unit

  • adsense_get_ad_unit_ad_code

  • adsense_list_linked_custom_channels

  • adsense_list_url_channels

  • adsense_get_url_channel

  • adsense_list_custom_channels

  • adsense_get_custom_channel

  • adsense_list_linked_ad_units

Reports

  • adsense_list_saved_reports

  • adsense_get_saved_report

  • adsense_generate_saved_report

  • adsense_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 build

Live 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.

  1. 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 in src/index.ts.

  2. Run npm test and npm pack --dry-run to verify the build and published package contents.

  3. Commit and push the release to GitHub.

  4. Publish the public scoped package with npm publish --access public.

  5. Authenticate when necessary with mcp-publisher login github, then run mcp-publisher publish to publish the matching server.json version.

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

MIT

Available Tools

3 tools
adsense_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

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Google Ads campaign reporting and management via Claude, enabling GAQL queries, performance metrics, and campaign modifications.
      58 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying Google Analytics accounts, properties, reports, and realtime data using the Data API and Admin API.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      F
      maintenance
      MCP 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