{ "markdown": "
\n\n# ๐Ÿ” Search Console MCP\n\n**Google Search Console + Bing Webmaster Tools + GA4 + AdSense โ€” in one context window.**\n\nStop exporting CSVs. Start asking your AI agent questions about your site's traffic, rankings, and revenue.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://github.com/saurabhsharma2u/search-console-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/saurabhsharma2u/search-console-mcp/actions/workflows/ci.yml)\n[![Stars](https://img.shields.io/github/stars/saurabhsharma2u/search-console-mcp?style=social)](https://github.com/saurabhsharma2u/search-console-mcp/stargazers)\n\n
\n\n[![Download MCPB Bundle](https://img.shields.io/badge/๐Ÿ“ฆ%20Download%20.mcpb-One--Click%20Bundle-D97706?style=for-the-badge&logo=claude&logoColor=white)](https://github.com/saurabhsharma2u/search-console-mcp/releases/latest/download/search-console-mcp.mcpb)\n\n[๐Ÿ“š Docs](https://searchconsolemcp.saurabh.app/) ยท [Quick Start](#-quick-start) ยท [Tools](#-tools) ยท [Backward Compatibility](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility) ยท [Security](#-security)\n\n
\n\n---\n\n## โšก What's New in v2.1.2\n\n* ๐Ÿค– **GenAI Query Insights (`genai_query_insights`)**: Surfaces likely generative-AI / AI-Mode / conversational \"fanout\" queries across Google and Bing. This is **custom heuristic logic** โ€” no official API is provided by Google or Bing for GenAI citation data, so it flags prompt verbs, follow-ups, acknowledgements, and conversational phrasing on the regular query data both engines already return. See [docs โ†’](https://searchconsolemcp.saurabh.app/tools/seo-intelligence)\n* ๐Ÿชฒ **`analytics_query` fix**: `rowLimit` is now honored instead of being silently ignored (previously always returned up to 1000 rows); `limit` remains as a backward-compatible alias.\n\n
\nWhat's New in v2.1.0\n\n* ๐Ÿ’ฐ **Google AdSense Integration**: Earnings reports, payments and account alerts via `setup --engine=adsense`. Enabling AdSense requires you to approve a separate `adsense.readonly` OAuth scope; your existing GSC, Bing, and GA4 configuration remains unchanged until you opt in.\n* ๐Ÿ” **OAuth-only AdSense auth**: The AdSense Management API supports user OAuth only โ€” setup now validates access live and rejects unsupported service-account configs with actionable guidance. Multi-account users get explicit publisher-account selection with full pagination (>100 accounts).\n* ๐Ÿ“Š **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.\n* ๐Ÿงช **End-to-end MCP test suite**: The built server binary is now tested over stdio and SSE exactly like an MCP host would drive it โ€” handshake, tool schemas, error envelopes, and multi-account resource behavior (11 e2e tests wired into CI).\n\n
\n\n
\nWhat's New in v2.0.x\n\n* ๐Ÿ’ฐ **Google AdSense Integration**: Earnings reports, payments and account alerts via `setup --engine=adsense`. Enabling AdSense requires you to approve a separate `adsense.readonly` OAuth scope; your existing GSC, Bing, and GA4 configuration remains unchanged until you opt in.\n* ๐Ÿ” **OAuth-only AdSense auth**: The AdSense Management API supports user OAuth only โ€” setup now validates access live and rejects unsupported service-account configs with actionable guidance. Multi-account users get explicit publisher-account selection with full pagination (>100 accounts).\n* ๐Ÿ“Š **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.\n* ๐Ÿงช **End-to-end MCP test suite**: The built server binary is now tested over stdio and SSE exactly like an MCP host would drive it โ€” handshake, tool schemas, error envelopes, and multi-account resource behavior (11 e2e tests wired into CI).\n\n
\nWhat's New in v2.0.x\n\n* ๐Ÿ“ฆ **MCPB One-Click Bundle Support (`.mcpb`)**: Drag and drop bundle installation for Claude Desktop.\n* โšก **Parallel Fetch Engine (`engine: \"all\"`)**: Multi-engine queries fetch Google, Bing, and GA4 concurrently with **50%+ lower latency**.\n* ๐Ÿ”„ **100% Backward Compatibility**: All ~96 legacy tool names continue to work seamlessly via our fallback router. [Read Backward Compatibility Guide โ†’](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)\n\n
\n\n---\n\n## Why this exists\n\nSite data lives in four different silos. Answering one question โ€”\n*\"did my ad revenue drop because of a traffic dip or a lower RPM?\"*\nโ€” usually means logging into four dashboards, exporting four CSVs,\nand doing VLOOKUPs by hand.\n\nSearch Console MCP puts **GSC, Bing, GA4, and AdSense** behind one\nset of tools your AI agent can call directly, and does the analysis\n(cannibalization, anomaly detection, revenue attribution) *before*\nthe data ever reaches your context window.\n\n| | Before | After |\n| ------------ | ------------------------------ | ------------------------------------------------ |\n| **Data** | 4 dashboards, manual exports | 1 unified context |\n| **Analysis** | Manual VLOOKUPs & pivot tables | Deterministic SEO + revenue math, server-side |\n| **Accounts** | Constant re-login | 20+ accounts, auto-resolved per site |\n| **Insight** | Raw rows, agent guesses | Curated signals (opportunity scores, anomalies) |\n\n---\n\n## โšก Quick Start\n\n```bash\nnpx search-console-mcp setup\n```\n\nThis opens your browser, authorizes your Google account, and stores your credentials securely (see [Security](#-security)). Then add it to your MCP client config (Claude Desktop, Cursor, Antigravity, etc.):\n\n```json\n{\n \"mcpServers\": {\n \"search-console\": {\n \"command\": \"npx\",\n \"args\": [\"search-console-mcp\"]\n }\n }\n}\n```\n\nRestart your client โ€” and try one of the prompts below.\n\n---\n\n## ๐Ÿ’ฌ Try it\n\nPaste these straight into your agent:\n\n> **\"My traffic dropped this week vs. last. Find exactly when it started and which pages are responsible.\"**\n\n> **\"Find keywords for example.com ranking positions 8โ€“15 with 1,000+ impressions โ€” my best quick wins.\"**\n\n> **\"Check for keyword cannibalization โ€” are two of my pages competing for the same query?\"**\n\n> **\"Run `seo_audit` on my top pages: which have high search visibility but poor CTR?\"**\n\n
\nMore example prompts\n\n- *\"Run a full SEO health check (`site_health_check`), segmented by Brand vs Non-Brand.\"*\n- *\"Fetch my top 5 pages by impressions and run `pagespeed_analyze` โ€” any correlation with declining rankings?\"*\n- *\"Compare Google vs Bing performance for the last 30 days (`compare_engines`) โ€” where is Bing winning?\"*\n- *\"Submit my latest URLs to Google and IndexNow using `indexing_submit` with `method: \"index_now\"`.\"*\n\n
\n\n---\n\n## ๐Ÿ”Œ Connect your accounts\n\n| Platform | Method | Setup |\n|---|---|---|\n| **Google Search Console** | OAuth (recommended) | `npx search-console-mcp setup` |\n| **Google Search Console** | Service Account | Set `GOOGLE_APPLICATION_CREDENTIALS` โ€” [details](#service-account-advanced) |\n| **Bing Webmaster Tools** | API Key | `export BING_API_KEY=\"...\"` โ€” [get a key](https://www.bing.com/webmasters/settings/api) |\n| **Google Analytics 4** | Service Account | `npx search-console-mcp setup --engine=ga4` |\n| **Google AdSense** | OAuth (read-only) | `npx search-console-mcp setup --engine=adsense` โ€” [headless servers](#headless-servers) |\n\nManage everything from the CLI:\n\n```bash\nnpx search-console-mcp accounts list\nnpx search-console-mcp accounts add-site --account=you@company.com --site=example.com\nnpx search-console-mcp accounts remove --account=you@company.com\n```\n\nWhen your agent queries a site, the server auto-resolves which account owns it โ€” no manual switching. [Multi-account docs โ†’](https://searchconsolemcp.saurabh.app/getting-started/multi-account)\n\n
\nHeadless servers (Docker, CI, VPS)\n\nAdSense cannot use service accounts, and config files are machine-encrypted โ€” so authorize once on any machine with a browser and transfer the grant:\n\n```bash\n# 1. On your laptop (after setup --engine=adsense):\nnpx search-console-mcp adsense-export\n\n# 2. On the server (prints a ready-to-run command on step 1):\nnpx search-console-mcp adsense-import --token='...' --publisher-id='accounts/pub-...'\n```\n\nThe token is stored encrypted on the server and auto-refreshes โ€” no browser needed again. Setup over SSH also works directly: when no browser is detected, `setup` prints the authorization URL plus `ssh -L 3000:localhost:3000` port-forward instructions instead of failing.\n\n
\n\n---\n\n## ๐Ÿ–ฅ๏ธ Run tools from the CLI\n\nSearch Console MCP also exposes registered MCP tools as direct CLI commands. Use the `run` subcommand to list tools, inspect tool-specific arguments, and print results as JSON, CSV, or an ASCII table:\n\n```bash\n# List registered tools\nnpx search-console-mcp run --help\n\n# Show options for one tool\nnpx search-console-mcp run analytics_query --help\n\n# Run an SEO audit with JSON output\nnpx search-console-mcp run seo_audit --siteUrl=https://example.com --type=quick_wins\n\n# Print array results as CSV or a table\nnpx search-console-mcp run analytics_query --siteUrl=https://example.com --startDate=2026-06-01 --endDate=2026-06-30 --dimensions=date,query --format=csv\nnpx search-console-mcp run sites_list --engine=all --format=table\n```\n\n
\nService Account setup (for servers/automation)\n\n1. Create a service account in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts)\n2. Generate a JSON key\n3. Add the service account email as a user in Search Console with \"Full\" or \"Restricted\" access\n4. `export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/key.json\"`\n\n
\n\n---\n\n## ๐Ÿ›  Tools (Fluent Domain Architecture)\n\nSearch Console MCP v2.0 features **7 Fluent Domain Tools** that handle all SEO, Analytics, Inspection, and Indexing operations cleanly:\n\n| Fluent Tool | Parameters / Actions | Description |\n|---|---|---|\n| `sites_list` | `engine: \"all\" \\| \"google\" \\| \"bing\"` | Lists verified sites across search engines in parallel |\n| `sites_manage` | `action: \"add\" \\| \"delete\"`, `siteUrl`, `engine` | Adds or removes site properties |\n| `accounts_manage` | `action: \"list\" \\| \"add_site\" \\| \"remove\"` | Configures multi-account profiles |\n| `sitemaps_list` | `siteUrl`, `feedUrl`, `engine` | Fetches sitemap status and indexing state |\n| `sitemaps_submit` | `siteUrl`, `feedUrl`, `engine` | Submits sitemaps to GSC & Bing |\n| `sitemaps_delete` | `siteUrl`, `feedUrl`, `engine` | Removes sitemaps |\n| `analytics_query` | `siteUrl`, `engine`, `dimensions`, `metrics` | Multi-engine search & GA4 analytics query |\n| `analytics_compare` | `mode: \"period_over_period\" \\| \"trends\" \\| \"drop_attribution\"` | Analyzes period deltas, trend shifts, and drop causes |\n| `analytics_anomalies`| `siteUrl`, `threshold` | Statistical detection of traffic spikes/drops |\n| `inspection_inspect`| `siteUrl`, `urls`, `engine` | Google URL inspection & Bing URL info |\n| `pagespeed_analyze` | `url`, `strategy`, `cwvOnly` | Core Web Vitals and PageSpeed Insights audits |\n| `indexing_submit` | `urls`, `method: \"standard\" \\| \"index_now\" \\| \"remove\"` | Instantly indexes URLs via IndexNow or Google/Bing API |\n| `indexing_status` | `siteUrl`, `type: \"quota\" \\| \"status\"` | Checks remaining indexing quota & URL status |\n| `seo_audit` | `type: \"quick_wins\" \\| \"striking_distance\" \\| \"cannibalization\" \\| \"low_hanging_fruit\" \\| \"lost_queries\" \\| \"recommendations\" \\| \"brand_vs_nonbrand\"` | Comprehensive automated SEO audits |\n| `seo_keywords_research`| `keywords`, `type: \"stats\" \\| \"related\" \\| \"traffic\"` | Keyword volumes and related keyword stats |\n| `site_health_check` | `siteUrl`, `level: \"summary\" \\| \"full\" \\| \"crawl_issues\"` | One-shot site performance & technical audit |\n| `compare_engines` | `siteUrl` | Side-by-side Google vs Bing performance breakdown |\n| `genai_query_insights` | `siteUrl`, `days`, `engine: \"google\" \\| \"bing\" \\| \"all\"`, `includePages`, `minImpressions` | Flags likely generative-AI / conversational queries (custom heuristic, no official API) |\n\n### Google AdSense Tools\n\n| Tool | Parameters | Description |\n|---|---|---|\n| `adsense_accounts` | `mode: \"configured\" \\| \"discover\"`, `accountId` | Lists configured or discoverable AdSense publisher accounts |\n| `adsense_report` | `dateRange`, `startDate`, `endDate`, `dimensions`, `metrics`, `orderBy`, `rowLimit`, `accountId` | Earnings, impressions, clicks, CTR & RPM with dimension breakdowns. Custom dates override `dateRange`. |\n| `adsense_payments_alerts` | `accountId` | Outstanding payments and account alerts (policy issues, payment holds) |\n\n> **Note:** `accountId` refers to the configured profile ID (e.g. `adsense_2`, as shown by `accounts_manage`), not a publisher resource name like `accounts/pub-123`.\n\n
\nBackward Compatibility Notice (96+ Legacy Tools)\n\nAll legacy tool names (`bing_sites_list`, `seo_quick_wins`, `sitemaps_get`, `bing_index_now`, `indexing_submit_url`, `opportunity_matrix`, etc.) continue to work transparently via our fallback router.\n\nRead our complete [Backward Compatibility & Migration Guide โ†’](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)\n\n
\n\n---\n\n## ๐Ÿ”’ Security\n\n- **OS keychain first** โ€” tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service\n- **AES-256-GCM fallback** โ€” encrypted with a key derived from your machine's hardware ID; a stolen file is useless on another device\n- **Minimal storage** โ€” only `refresh_token` and `expiry_date` are persisted, at `mode 600`\n- **Silent refresh** โ€” tokens renew automatically in the background\n\n---\n\n## License\n\n[MIT](./LICENSE) ยท [Contributing guide](./CONTRIBUTING.md) ยท [Backward Compatibility Guide](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)\n\n
\n\nIf this saves you a spreadsheet, consider โญ starring the repo.\n\n
", "bytes": 14378, "sha": "c27c3f6d1a3b5ebbcebc5ddf6d91765920c0d503fad50c8c135eb3de1b0a1eb7", "repo_slug": "saurabhsharma2u/search-console-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_saurabhsharma2u_search_console_731fa407/readme" }