{"_id":"@appsyogi/adsense-mcp-server","_rev":"2-e78e70b6f35c17a42da77ef7ac64dcde","name":"@appsyogi/adsense-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@appsyogi/adsense-mcp-server","version":"0.1.0","keywords":["mcp","google-adsense","adsense","earnings","publisher","model-context-protocol","claude","cursor","ai","monetization"],"author":{"name":"SuperZero11"},"license":"MIT","_id":"@appsyogi/adsense-mcp-server@0.1.0","maintainers":[{"name":"superzero11","email":"rahul.vit09@gmail.com"}],"homepage":"https://github.com/AppsYogi-com/adsense-mcp-server#readme","bugs":{"url":"https://github.com/AppsYogi-com/adsense-mcp-server/issues"},"bin":{"adsense-mcp":"dist/cli/index.js"},"dist":{"shasum":"49b1629633afc50a16266f7a66363f5c5bedd98e","tarball":"https://registry.npmjs.org/@appsyogi/adsense-mcp-server/-/adsense-mcp-server-0.1.0.tgz","fileCount":9,"integrity":"sha512-2x0uZLSE6Pm64yeRdC9JMb7YhHwLuycvR1bJbNQZ770eypjGbtN5Zz39sOqvdhw9Zn+mMXJXAJuOWssPKSZW7w==","signatures":[{"sig":"MEYCIQD1VGNVSd+Vg32/Jkt2rHq6u3bxH+bwSG+5PEcksiVBkAIhAMyUXC5TyAD6ohQB1QY3/Pnd89skVBD9FAAE61JFINMG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@appsyogi%2fadsense-mcp-server@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":382354},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c8c9cb6b5a72cba27bf68b1e253bca1271f125c5","scripts":{"dev":"tsup --watch","lint":"eslint src/","build":"tsup","start":"node dist/cli/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"superzero11","email":"rahul.vit09@gmail.com"},"repository":{"url":"git+https://github.com/AppsYogi-com/adsense-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"Google AdSense MCP Server - Monitor earnings, reports, and account health via Claude/AI","directories":{},"_nodeVersion":"20.19.6","dependencies":{"ora":"^8.0.0","open":"^10.0.0","chalk":"^5.3.0","keytar":"^7.9.0","commander":"^12.0.0","env-paths":"^3.0.0","googleapis":"^140.0.0","better-sqlite3":"^11.0.0","@modelcontextprotocol/sdk":"^1.25.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/adsense-mcp-server_0.1.0_1768883589455_0.2697050867136974","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-01-20T04:33:09.374Z","modified":"2026-03-27T10:27:02.785Z","0.1.0":"2026-01-20T04:33:09.651Z"},"bugs":{"url":"https://github.com/AppsYogi-com/adsense-mcp-server/issues"},"author":{"name":"SuperZero11"},"license":"MIT","homepage":"https://github.com/AppsYogi-com/adsense-mcp-server#readme","keywords":["mcp","google-adsense","adsense","earnings","publisher","model-context-protocol","claude","cursor","ai","monetization"],"repository":{"url":"git+https://github.com/AppsYogi-com/adsense-mcp-server.git","type":"git"},"description":"Google AdSense MCP Server - Monitor earnings, reports, and account health via Claude/AI","maintainers":[{"email":"vssmartniceman97@gmail.com","name":"vaibhavrajput"},{"email":"rahul.vit09@gmail.com","name":"superzero11"}],"readme":"# Google AdSense MCP Server\n\nA CLI-installable MCP (Model Context Protocol) server that enables Claude, Cursor, and other AI assistants to interact with your Google AdSense account.\n\n## Features\n\n- 📊 **Earnings Summary** - Quick overview of today, yesterday, last 7 days, and monthly earnings\n- 📈 **Detailed Reports** - Generate reports with dimensions (date, site, country, ad unit) and metrics\n- 🔄 **Period Comparison** - Compare performance between time periods\n- 🌐 **Site Status** - Check approval status for all your sites\n- ⚠️ **Alerts & Policy Issues** - Monitor account health and catch violations early\n- 💰 **Payment History** - View payment history and pending earnings\n- 📦 **Ad Units** - List ad units and get embed codes\n- 📤 **CSV Export** - Export reports for further analysis\n\n## Installation\n\n```bash\nnpx @appsyogi/adsense-mcp-server init\n```\n\n## Quick Start\n\n### 1. Initialize (OAuth Setup)\n\n```bash\nnpx adsense-mcp init\n```\n\nThis will:\n- Open your browser for Google sign-in\n- Request read-only access to your AdSense data\n- Let you select your default account (if you have multiple)\n- Store credentials securely\n\n### 2. Verify Setup\n\n```bash\nnpx adsense-mcp doctor\n```\n\n### 3. Add to Your MCP Client\n\n#### VS Code Copilot (`~/.vscode/mcp.json`)\n\n```json\n{\n    \"servers\": {\n        \"adsense\": {\n            \"command\": \"npx\",\n            \"args\": [\"@appsyogi/adsense-mcp-server\", \"run\"],\n            \"type\": \"stdio\"\n        }\n    }\n}\n```\n\n#### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)\n\n```json\n{\n    \"mcpServers\": {\n        \"adsense\": {\n            \"command\": \"npx\",\n            \"args\": [\"@appsyogi/adsense-mcp-server\", \"run\"]\n        }\n    }\n}\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `adsense_list_accounts` | List all AdSense accounts you have access to |\n| `adsense_earnings_summary` | Quick earnings overview (today, yesterday, last 7 days, this month) |\n| `adsense_generate_report` | Generate detailed reports with custom dimensions and metrics |\n| `adsense_compare_periods` | Compare performance between two time periods |\n| `adsense_list_sites` | List all sites with their approval status |\n| `adsense_list_alerts` | Get account alerts and warnings |\n| `adsense_list_policy_issues` | Check for policy violations |\n| `adsense_list_payments` | View payment history and pending earnings |\n| `adsense_list_ad_units` | List all ad units |\n| `adsense_get_ad_code` | Get HTML embed code for an ad unit |\n| `adsense_export_csv` | Export report data as CSV |\n\n## Example Conversations\n\n### Check Earnings\n```\nYou: How's my AdSense doing today?\n\nClaude: 📊 **AdSense Earnings Summary**\n\n| Period | Earnings | Impressions | Clicks | CTR |\n|--------|----------|-------------|--------|-----|\n| Today | $8.45 | 3,200 | 28 | 0.88% |\n| Yesterday | $15.67 | 6,200 | 52 | 0.84% |\n| Last 7 Days | $98.45 | 42,000 | 380 | 0.90% |\n| This Month | $345.67 | 150,000 | 1,350 | 0.90% |\n\nYou're tracking 16% ahead of last month at this point! 🎉\n```\n\n### Check Site Status\n```\nYou: Is my new site approved yet?\n\nClaude: 📋 **Site Status**\n\n| Site | Status | Notes |\n|------|--------|-------|\n| example.com | ✅ READY | Ads serving |\n| blog.example.com | ⏳ GETTING_READY | Under review |\n| newsite.com | ⚠️ NEEDS_ATTENTION | Insufficient content |\n```\n\n### Generate Report\n```\nYou: Show me earnings by country for last week\n\nClaude: [Generates report with COUNTRY_NAME dimension]\n```\n\n## CLI Commands\n\n### `adsense-mcp init`\nSet up OAuth authentication and select default account.\n\n```bash\n# Interactive setup\nnpx adsense-mcp init\n\n# Set specific default account\nnpx adsense-mcp init --account pub-1234567890123456\n\n# Use service account (advanced)\nnpx adsense-mcp init --service-account /path/to/key.json\n```\n\n### `adsense-mcp doctor`\nVerify your setup and check account health.\n\n```bash\nnpx adsense-mcp doctor\n```\n\n### `adsense-mcp run`\nStart the MCP server (typically called by your MCP client).\n\n```bash\n# Use default account\nnpx adsense-mcp run\n\n# Use specific account\nnpx adsense-mcp run --account pub-9876543210987654\n\n# Verbose logging\nnpx adsense-mcp run --verbose\n```\n\n## Multi-Account Support\n\nIf you have multiple AdSense accounts, you can:\n\n1. Select default during `init`\n2. Override with `--account` flag\n3. Use `adsense_list_accounts` tool to see all accounts\n4. Pass `accountId` parameter to any tool\n\n## Data Storage\n\nAll data is stored locally in `~/.config/adsense-mcp/`:\n\n- `config.json` - Default account and settings\n- `tokens.json` - OAuth refresh token (encrypted)\n- `cache.sqlite` - Report cache for faster responses\n\n## Security\n\n- **Read-only access** - This server only requests `adsense.readonly` scope\n- **Secure token storage** - Tokens are encrypted using OS keychain (via keytar)\n- **Local only** - All data stays on your machine\n- **No telemetry** - We don't collect any usage data\n\n## Rate Limits\n\nThe AdSense API has strict rate limits (100 requests/minute). This server:\n- Caches responses intelligently (5min-24hr based on data type)\n- Implements exponential backoff for retries\n- Tracks request rates to avoid hitting limits\n\n## Troubleshooting\n\n### \"No tokens found\" error\nRun `npx adsense-mcp init` to set up authentication.\n\n### \"Rate limit exceeded\" error\nWait a minute and try again. The server will automatically retry with backoff.\n\n### \"Account not found\" error\nMake sure you've selected a valid account during setup. Run `npx adsense-mcp doctor` to see available accounts.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue or PR on GitHub.\n","readmeFilename":"README.md"}