Skip to content
Back to search

search-console-mcp

Search & analytics data as infrastructure — MCP server for Google Search Console, Bing Webmaster Tools, Google Adsense and GA4, designed for AI agents and automation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/saurabhsharma2u--search-console-mcp/badge.svg)](/listings/saurabhsharma2u--search-console-mcp)

HTML

<a href="/listings/saurabhsharma2u--search-console-mcp"><img src="/api/listings/saurabhsharma2u--search-console-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx search-console-mcp setup

This 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.):

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["search-console-mcp"]
    }
  }
}

Restart your client — and try one of the prompts below.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 268 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # 🔍 Search Console MCP
  3. **Google Search Console + Bing Webmaster Tools + GA4 + AdSense — in one context window.**
  4. Stop exporting CSVs. Start asking your AI agent questions about your site's traffic, rankings, and revenue.
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![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)
  7. [![Stars](https://img.shields.io/github/stars/saurabhsharma2u/search-console-mcp?style=social)](https://github.com/saurabhsharma2u/search-console-mcp/stargazers)
  8. <br/>
  9. [![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)
  10. [📚 Docs](https://searchconsolemcp.saurabh.app/) · [Quick Start](#-quick-start) · [Tools](#-tools) · [Backward Compatibility](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility) · [Security](#-security)
  11. </div>
  12. ---
  13. ## ⚡ What's New in v2.1.4
  14. * 🎯 **Correct-property resolution (`#110`)**: Accounts with multiple verified properties sharing one hostname (locale subfolders like `/en-gb/` + `/de-de/`, the root property, and the `sc-domain:` property) could get **analytics data silently returned for the wrong property** — whichever colliding property the resolver happened to touch first. Resolution is now exact by property type and path; bare-domain queries rank deterministically (`sc-domain:` › root), and truly ambiguous requests fail with the list of matching properties instead of guessing. *With thanks to [Alcip](https://github.com/Alcip) for the outstanding root-cause analysis in #110.*
  15. * 🔐 **Explicit write authorization for GSC mutation tools (`#113`)**: `sitemaps_submit`, `sitemaps_delete` and site-management calls now require an explicit webmasters write scope, offered as an inline re-authorization flow in the CLI when a tool first needs it. The server stays read-only by default at setup; you opt into write capabilities explicitly. *Credit to [chase-weiser88](https://github.com/chase-weiser88) for surfacing the missing write scope in #84.*
  16. * 🛡️ **SSE transport secured & deprecated (`#114`)**: SSE mode now binds to `127.0.0.1` by default (`--host=`/`MCP_HTTP_HOST` to override), requires a bearer token (`--token=`/`MCP_HTTP_TOKEN`, auto-generated if unset), never sends wildcard CORS, and rejects forged non-loopback Host headers (DNS-rebinding guard). **SSE mode is deprecated** and will be removed in the next release — prefer the default stdio transport.
  17. * 🪲 **`find_quick_wins` prompt typing (`#112`)**: `min_impressions` was declared as a number, but MCP clients must send prompt arguments as strings — so every use errored with `expected number, received string`. It is now string-typed and coerced internally (`1000` default preserved).
  18. <details>
  19. <summary><strong>What's New in v2.1.2</strong></summary>
  20. * 🤖 **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)
  21. * 🪲 **`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.
  22. </details>
  23. <details>
  24. <summary><strong>What's New in v2.1.0</strong></summary>
  25. * 💰 **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.
  26. * 🔐 **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).
  27. * 📊 **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.
  28. * 🧪 **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).
  29. </details>
  30. <details>
  31. <summary><strong>What's New in v2.0.x</strong></summary>
  32. * 💰 **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.
  33. * 🔐 **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).
  34. * 📊 **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.
  35. * 🧪 **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).
  36. <details>
  37. <summary><strong>What's New in v2.0.x</strong></summary>
  38. * 📦 **MCPB One-Click Bundle Support (`.mcpb`)**: Drag and drop bundle installation for Claude Desktop.
  39. * ⚡ **Parallel Fetch Engine (`engine: "all"`)**: Multi-engine queries fetch Google, Bing, and GA4 concurrently with **50%+ lower latency**.
  40. * 🔄 **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)
  41. </details>
  42. ---
  43. ## Why this exists
  44. Site data lives in four different silos. Answering one question —
  45. *"did my ad revenue drop because of a traffic dip or a lower RPM?"*
  46. — usually means logging into four dashboards, exporting four CSVs,
  47. and doing VLOOKUPs by hand.
  48. Search Console MCP puts **GSC, Bing, GA4, and AdSense** behind one
  49. set of tools your AI agent can call directly, and does the analysis
  50. (cannibalization, anomaly detection, revenue attribution) *before*
  51. the data ever reaches your context window.
  52. | | Before | After |
  53. | ------------ | ------------------------------ | ------------------------------------------------ |
  54. | **Data** | 4 dashboards, manual exports | 1 unified context |
  55. | **Analysis** | Manual VLOOKUPs & pivot tables | Deterministic SEO + revenue math, server-side |
  56. | **Accounts** | Constant re-login | 20+ accounts, auto-resolved per site |
  57. | **Insight** | Raw rows, agent guesses | Curated signals (opportunity scores, anomalies) |
  58. ---
  59. ## ⚡ Quick Start
  60. ```bash
  61. npx search-console-mcp setup
  62. ```
  63. This 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.):
  64. ```json
  65. {
  66. "mcpServers": {
  67. "search-console": {
  68. "command": "npx",
  69. "args": ["search-console-mcp"]
  70. }
  71. }
  72. }
  73. ```
  74. Restart your client — and try one of the prompts below.
  75. ---
  76. ## 💬 Try it
  77. Paste these straight into your agent:
  78. > **"My traffic dropped this week vs. last. Find exactly when it started and which pages are responsible."**
  79. > **"Find keywords for example.com ranking positions 8–15 with 1,000+ impressions — my best quick wins."**
  80. > **"Check for keyword cannibalization — are two of my pages competing for the same query?"**
  81. > **"Run `seo_audit` on my top pages: which have high search visibility but poor CTR?"**
  82. <details>
  83. <summary>More example prompts</summary>
  84. - *"Run a full SEO health check (`site_health_check`), segmented by Brand vs Non-Brand."*
  85. - *"Fetch my top 5 pages by impressions and run `pagespeed_analyze` — any correlation with declining rankings?"*
  86. - *"Compare Google vs Bing performance for the last 30 days (`compare_engines`) — where is Bing winning?"*
  87. - *"Submit my latest URLs to Google and IndexNow using `indexing_submit` with `method: "index_now"`."*
  88. </details>
  89. ---
  90. ## 🔌 Connect your accounts
  91. | Platform | Method | Setup |
  92. |---|---|---|
  93. | **Google Search Console** | OAuth (recommended) | `npx search-console-mcp setup` |
  94. | **Google Search Console** | Service Account | Set `GOOGLE_APPLICATION_CREDENTIALS` — [details](#service-account-advanced) |
  95. | **Bing Webmaster Tools** | API Key | `export BING_API_KEY="..."` — [get a key](https://www.bing.com/webmasters/settings/api) |
  96. | **Google Analytics 4** | Service Account | `npx search-console-mcp setup --engine=ga4` |
  97. | **Google AdSense** | OAuth (read-only) | `npx search-console-mcp setup --engine=adsense` — [headless servers](#headless-servers) |
  98. Manage everything from the CLI:
  99. ```bash
  100. npx search-console-mcp accounts list
  101. npx search-console-mcp accounts add-site --account=you@company.com --site=example.com
  102. npx search-console-mcp accounts remove --account=you@company.com
  103. ```
  104. When 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)
  105. <details>
  106. <summary id="headless-servers">Headless servers (Docker, CI, VPS)</summary>
  107. AdSense cannot use service accounts, and config files are machine-encrypted — so authorize once on any machine with a browser and transfer the grant:
  108. ```bash
  109. # 1. On your laptop (after setup --engine=adsense):
  110. npx search-console-mcp adsense-export
  111. # 2. On the server (prints a ready-to-run command on step 1):
  112. npx search-console-mcp adsense-import --token='...' --publisher-id='accounts/pub-...'
  113. ```
  114. The 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.
  115. </details>
  116. ---
  117. ## 🖥️ Run tools from the CLI
  118. Search 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:
  119. ```bash
  120. # List registered tools
  121. npx search-console-mcp run --help
  122. # Show options for one tool
  123. npx search-console-mcp run analytics_query --help
  124. # Run an SEO audit with JSON output
  125. npx search-console-mcp run seo_audit --siteUrl=https://example.com --type=quick_wins
  126. # Print array results as CSV or a table
  127. npx search-console-mcp run analytics_query --siteUrl=https://example.com --startDate=2026-06-01 --endDate=2026-06-30 --dimensions=date,query --format=csv
  128. npx search-console-mcp run sites_list --engine=all --format=table
  129. ```
  130. <details>
  131. <summary id="service-account-advanced">Service Account setup (for servers/automation)</summary>
  132. 1. Create a service account in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts)
  133. 2. Generate a JSON key
  134. 3. Add the service account email as a user in Search Console with "Full" or "Restricted" access
  135. 4. `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`
  136. </details>
  137. ---
  138. ## 🛠 Tools (Fluent Domain Architecture)
  139. Search Console MCP v2.0 features **7 Fluent Domain Tools** that handle all SEO, Analytics, Inspection, and Indexing operations cleanly:
  140. | Fluent Tool | Parameters / Actions | Description |
  141. |---|---|---|
  142. | `sites_list` | `engine: "all" \| "google" \| "bing"` | Lists verified sites across search engines in parallel |
  143. | `sites_manage` | `action: "add" \| "delete"`, `siteUrl`, `engine` | Adds or removes site properties |
  144. | `accounts_manage` | `action: "list" \| "add_site" \| "remove"` | Configures multi-account profiles |
  145. | `sitemaps_list` | `siteUrl`, `feedUrl`, `engine` | Fetches sitemap status and indexing state |
  146. | `sitemaps_submit` | `siteUrl`, `feedUrl`, `engine` | Submits sitemaps to GSC & Bing |
  147. | `sitemaps_delete` | `siteUrl`, `feedUrl`, `engine` | Removes sitemaps |
  148. | `analytics_query` | `siteUrl`, `engine`, `dimensions`, `metrics` | Multi-engine search & GA4 analytics query |
  149. | `analytics_compare` | `mode: "period_over_period" \| "trends" \| "drop_attribution"` | Analyzes period deltas, trend shifts, and drop causes |
  150. | `analytics_anomalies`| `siteUrl`, `threshold` | Statistical detection of traffic spikes/drops |
  151. | `inspection_inspect`| `siteUrl`, `urls`, `engine` | Google URL inspection & Bing URL info |
  152. | `pagespeed_analyze` | `url`, `strategy`, `cwvOnly` | Core Web Vitals and PageSpeed Insights audits |
  153. | `indexing_submit` | `urls`, `method: "standard" \| "index_now" \| "remove"` | Instantly indexes URLs via IndexNow or Google/Bing API |
  154. | `indexing_status` | `siteUrl`, `type: "quota" \| "status"` | Checks remaining indexing quota & URL status |
  155. | `seo_audit` | `type: "quick_wins" \| "striking_distance" \| "cannibalization" \| "low_hanging_fruit" \| "lost_queries" \| "recommendations" \| "brand_vs_nonbrand"` | Comprehensive automated SEO audits |
  156. | `seo_keywords_research`| `keywords`, `type: "stats" \| "related" \| "traffic"` | Keyword volumes and related keyword stats |
  157. | `site_health_check` | `siteUrl`, `level: "summary" \| "full" \| "crawl_issues"` | One-shot site performance & technical audit |
  158. | `compare_engines` | `siteUrl` | Side-by-side Google vs Bing performance breakdown |
  159. | `genai_query_insights` | `siteUrl`, `days`, `engine: "google" \| "bing" \| "all"`, `includePages`, `minImpressions` | Flags likely generative-AI / conversational queries (custom heuristic, no official API) |
  160. ### Google AdSense Tools
  161. | Tool | Parameters | Description |
  162. |---|---|---|
  163. | `adsense_accounts` | `mode: "configured" \| "discover"`, `accountId` | Lists configured or discoverable AdSense publisher accounts |
  164. | `adsense_report` | `dateRange`, `startDate`, `endDate`, `dimensions`, `metrics`, `orderBy`, `rowLimit`, `accountId` | Earnings, impressions, clicks, CTR & RPM with dimension breakdowns. Custom dates override `dateRange`. |
  165. | `adsense_payments_alerts` | `accountId` | Outstanding payments and account alerts (policy issues, payment holds) |
  166. > **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`.
  167. <details>
  168. <summary><strong>Backward Compatibility Notice (96+ Legacy Tools)</strong></summary>
  169. All 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.
  170. Read our complete [Backward Compatibility & Migration Guide →](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)
  171. </details>
  172. ---
  173. ## 🔒 Security
  174. - **OS keychain first** — tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service
  175. - **AES-256-GCM fallback** — encrypted with a key derived from your machine's hardware ID; a stolen file is useless on another device
  176. - **Minimal storage** — only `refresh_token` and `expiry_date` are persisted, at `mode 600`
  177. - **Silent refresh** — tokens renew automatically in the background
  178. ---
  179. ## License
  180. [MIT](./LICENSE) · [Contributing guide](./CONTRIBUTING.md) · [Backward Compatibility Guide](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)
  181. <div align="center">
  182. If this saves you a spreadsheet, consider ⭐ starring the repo.
  183. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.