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

---

## Requirements

- Node.js 18+
- A Google AdSense account
- Claude Desktop

---

## Setup

### 1. Google Cloud

1. Go to [console.cloud.google.com](https://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

```bash
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:

```bash
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`

```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

```bash
# Build
npm run build

# Run directly (for testing)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
```

---

## License

MIT