adsense-mcp

MCP (Model Context Protocol) 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.

Built for solo developers who build websites with AI agents and want to monetize them without leaving the terminal.

Features

• Ad Unit CRUD — Create and manage ad units via AdSense Management API v2
• Ad Code Retrieval — Get ready-to-paste HTML/JS embed code for any ad unit
• Framework Snippets — Generate ad integration code for React, Next.js, Vue, Nuxt, Astro, Svelte
• ads.txt Automation — Generate and remotely verify ads.txt for your domains
• Earnings Reports — Query revenue, page views, clicks with flexible date ranges and dimensions
• Alerts & Payments — Monitor policy issues and payment history
• Auto-detection — Automatically resolves your account and ad client, so most parameters are optional
• Lightweight — Uses direct REST calls instead of the heavy googleapis package

Prerequisites

1. Active Google AdSense account (already approved)
2. Node.js 18+
3. Google Cloud OAuth credentials (see Setup below)

Setup

1. Create Google Cloud OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the AdSense Management API:
   • Navigate to APIs & Services > Library
   • Search for "AdSense Management API"
   • Click Enable
4. Create OAuth credentials:
   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Choose Desktop app as the application type
   • Download the JSON file
5. Configure the OAuth consent screen:
   • Go to APIs & Services > OAuth consent screen
   • Keep the publishing status as Testing
   • Add your Google account as a Test user

Note: While in "Testing" mode, only test users you add can authenticate. This is fine for personal use — no Google review required.

2. Install

npm install -g adsense-mcp

3. Authenticate

adsense-mcp auth /path/to/downloaded-credentials.json

This will:

• Save your OAuth credentials to ~/.adsense-mcp/credentials.json
• Open your browser for Google OAuth consent
• Save access/refresh tokens to ~/.adsense-mcp/tokens.json

You only need to do this once. Tokens auto-refresh on subsequent use.

4. Configure Your AI Tool

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "adsense": {
      "command": "npx",
      "args": ["-y", "adsense-mcp"]
    }
  }
}

Or add globally in ~/.claude/settings.json:

{
  "mcpServers": {
    "adsense": {
      "command": "npx",
      "args": ["-y", "adsense-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "adsense": {
      "command": "npx",
      "args": ["-y", "adsense-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "adsense": {
      "command": "npx",
      "args": ["-y", "adsense-mcp"]
    }
  }
}

Tools Reference

Account & Configuration

list_accounts

List all AdSense accounts linked to your Google account.

Parameters: (none)

Example prompt: "Show me my AdSense accounts"

list_ad_clients

List ad clients (publisher IDs like ca-pub-XXXX) for an account.

Parameters:
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "What's my AdSense publisher ID?"

list_sites

List all sites with their approval status and auto-ads setting.

Parameters:
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "Which sites are approved in my AdSense?"

Ad Unit Management

create_ad_unit

Create a new ad unit. Returns the unit name, slot ID, and state.

Parameters:
  displayName  (required)  Human-readable name (e.g., "Homepage Banner")
  type         (optional)  DISPLAY | IN_FEED | IN_ARTICLE | MATCHED_CONTENT (default: DISPLAY)
  adClient     (optional)  Ad client name. Auto-detected if omitted.

Example prompt: "Create a display ad unit called 'Sidebar Ad' for my blog"

list_ad_units

List all ad units with their name, display name, state, type, and size.

Parameters:
  adClient  (optional)  Ad client name. Auto-detected if omitted.

Example prompt: "List all my ad units"

get_ad_code

Get the raw HTML/JS ad code for a specific ad unit, as provided by Google.

Parameters:
  adUnit  (required)  Full ad unit name (e.g., accounts/pub-XXX/adclients/ca-pub-XXX/adunits/123)

Example prompt: "Get the embed code for my sidebar ad unit"

get_ad_snippet

Generate framework-specific ad component code, ready to drop into your project.

Parameters:
  framework    (required)  html | react | nextjs | vue | nuxt | astro | svelte
  publisherId  (required)  Publisher ID (e.g., ca-pub-1234567890123456)
  slotId       (required)  Ad unit slot ID (e.g., 1234567890)
  style        (optional)  responsive | in-article | in-feed | fixed (default: responsive)
  width        (optional)  Width in px (only for "fixed" style)
  height       (optional)  Height in px (only for "fixed" style)

Example prompt: "Generate a Next.js component for my ad unit slot 9876543210"

Supported frameworks and what gets generated:

| Framework | Output | |-----------|--------| | html | Standard <ins> tag with inline script | | react | AdUnit component with useEffect push | | nextjs | Layout with next/script + AdUnit component | | vue | SFC with onMounted push | | nuxt | nuxt.config.ts head config + Vue SFC | | astro | .astro component with is:inline script | | svelte | Component with onMount push |

ads.txt

generate_ads_txt

Generate the correct ads.txt content for your AdSense account.

Parameters:
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "Generate ads.txt for my site"

Returns the entry line and instructions for where to place the file in various project types.

verify_ads_txt

Fetch a domain's /ads.txt and check if it contains your publisher entry.

Parameters:
  domain   (required)  Domain to check (e.g., example.com)
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "Check if ads.txt is set up correctly on myblog.com"

Analytics

generate_report

Generate an earnings report with customizable date range, metrics, and dimensions.

Parameters:
  dateRange   (optional)  TODAY | YESTERDAY | LAST_7_DAYS | LAST_30_DAYS |
                          MONTH_TO_DATE | YEAR_TO_DATE | LAST_3_MONTHS | LAST_12_MONTHS
                          (default: LAST_7_DAYS)
  metrics     (optional)  Array of metrics (default: [ESTIMATED_EARNINGS, PAGE_VIEWS, CLICKS, PAGE_VIEWS_CTR])
  dimensions  (optional)  Array of dimensions (default: [DATE])
  account     (optional)  Account name. Auto-detected if omitted.

Available metrics: ESTIMATED_EARNINGS, PAGE_VIEWS, IMPRESSIONS, CLICKS, PAGE_VIEWS_CTR, COST_PER_CLICK, PAGE_VIEWS_RPM, AD_REQUESTS, AD_REQUESTS_CTR

Available dimensions: DATE, WEEK, MONTH, SITE_DOMAIN, AD_UNIT_NAME, COUNTRY_NAME, PLATFORM_TYPE

Example prompt: "Show my earnings for the last 30 days broken down by site"

list_alerts

List policy alerts and issues that need attention.

Parameters:
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "Are there any AdSense policy issues I should know about?"

list_payments

List payment history.

Parameters:
  account  (optional)  Account name. Auto-detected if omitted.

Example prompt: "Show my AdSense payment history"

Usage Examples

Full workflow: Add ads to a new Next.js site

You:  "I just deployed myblog.com with Next.js. Set up AdSense ads for it."

AI:   1. Calls list_accounts → gets your account
      2. Calls list_sites → confirms myblog.com is approved
      3. Calls create_ad_unit → creates "myblog-header" (DISPLAY)
      4. Calls create_ad_unit → creates "myblog-article" (IN_ARTICLE)
      5. Calls get_ad_snippet (nextjs) → generates Next.js components
      6. Calls generate_ads_txt → generates ads.txt content
      7. Inserts ad components into your layout and article pages
      8. Creates public/ads.txt
      9. Calls verify_ads_txt → confirms setup after deploy

Quick report

You:  "How are my ads performing this month?"

AI:   Calls generate_report with dateRange=MONTH_TO_DATE,
      dimensions=[DATE, SITE_DOMAIN]
      → Shows earnings trend by site

Ad placement for existing units

You:  "Add my existing ad units to this Astro blog"

AI:   1. Calls list_ad_units → gets your units and slot IDs
      2. Calls get_ad_snippet (astro) for each unit
      3. Inserts components into your Astro layouts

Troubleshooting

"Not authenticated" error

Re-run the auth flow:

adsense-mcp auth

If tokens exist but are invalid, delete them and re-authenticate:

rm ~/.adsense-mcp/tokens.json
adsense-mcp auth

"AdSense Management API has not been used" error

Enable the API in Google Cloud Console:

1. Go to APIs & Services > Library
2. Search "AdSense Management API"
3. Click Enable

"Access Not Configured" or 403 errors

Make sure:

• Your Google account is added as a test user in the OAuth consent screen
• The AdSense Management API is enabled in your GCP project
• Your AdSense account is active and approved

Token refresh failures

Delete the saved tokens and re-authenticate:

rm ~/.adsense-mcp/tokens.json
adsense-mcp auth

Security

• OAuth tokens are stored in ~/.adsense-mcp/tokens.json (file permission: user-only recommended)
• Credentials are stored in ~/.adsense-mcp/credentials.json
• The server uses https://www.googleapis.com/auth/adsense scope (full read/write)
• No data is sent to any third party — all API calls go directly to Google
• Auth callback runs on 127.0.0.1 with a randomly assigned port

To restrict to read-only access, modify the SCOPES array in src/auth.ts to:

const SCOPES = ['https://www.googleapis.com/auth/adsense.readonly'];

License

MIT