内容
<div align="center">
# 🔍 Search Console MCP
**Google Search Console + Bing Webmaster Tools + GA4 + AdSense — in one context window.**
Stop exporting CSVs. Start asking your AI agent questions about your site's traffic, rankings, and revenue.
[](https://opensource.org/licenses/MIT)
[](https://github.com/saurabhsharma2u/search-console-mcp/actions/workflows/ci.yml)
[](https://github.com/saurabhsharma2u/search-console-mcp/stargazers)
<br/>
[](https://github.com/saurabhsharma2u/search-console-mcp/releases/latest/download/search-console-mcp.mcpb)
[📚 Docs](https://searchconsolemcp.saurabh.app/) · [Quick Start](#-quick-start) · [Tools](#-tools) · [Backward Compatibility](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility) · [Security](#-security)
</div>
---
## ⚡ What's New in v2.1.2
* 🤖 **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)
* 🪲 **`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.
<details>
<summary><strong>What's New in v2.1.0</strong></summary>
* 💰 **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.
* 🔐 **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).
* 📊 **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.
* 🧪 **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).
</details>
<details>
<summary><strong>What's New in v2.0.x</strong></summary>
* 💰 **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.
* 🔐 **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).
* 📊 **`adsense_report` upgrades**: Custom `startDate`/`endDate` now override preset `dateRange`s, plus a new `orderBy` parameter (`-ESTIMATED_EARNINGS`) for sorted revenue reports.
* 🧪 **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).
<details>
<summary><strong>What's New in v2.0.x</strong></summary>
* 📦 **MCPB One-Click Bundle Support (`.mcpb`)**: Drag and drop bundle installation for Claude Desktop.
* ⚡ **Parallel Fetch Engine (`engine: "all"`)**: Multi-engine queries fetch Google, Bing, and GA4 concurrently with **50%+ lower latency**.
* 🔄 **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)
</details>
---
## Why this exists
Site data lives in four different silos. Answering one question —
*"did my ad revenue drop because of a traffic dip or a lower RPM?"*
— usually means logging into four dashboards, exporting four CSVs,
and doing VLOOKUPs by hand.
Search Console MCP puts **GSC, Bing, GA4, and AdSense** behind one
set of tools your AI agent can call directly, and does the analysis
(cannibalization, anomaly detection, revenue attribution) *before*
the data ever reaches your context window.
| | Before | After |
| ------------ | ------------------------------ | ------------------------------------------------ |
| **Data** | 4 dashboards, manual exports | 1 unified context |
| **Analysis** | Manual VLOOKUPs & pivot tables | Deterministic SEO + revenue math, server-side |
| **Accounts** | Constant re-login | 20+ accounts, auto-resolved per site |
| **Insight** | Raw rows, agent guesses | Curated signals (opportunity scores, anomalies) |
---
## ⚡ Quick Start
```bash
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.):
```json
{
"mcpServers": {
"search-console": {
"command": "npx",
"args": ["search-console-mcp"]
}
}
}
```
Restart your client — and try one of the prompts below.
---
## 💬 Try it
Paste these straight into your agent:
> **"My traffic dropped this week vs. last. Find exactly when it started and which pages are responsible."**
> **"Find keywords for example.com ranking positions 8–15 with 1,000+ impressions — my best quick wins."**
> **"Check for keyword cannibalization — are two of my pages competing for the same query?"**
> **"Run `seo_audit` on my top pages: which have high search visibility but poor CTR?"**
<details>
<summary>More example prompts</summary>
- *"Run a full SEO health check (`site_health_check`), segmented by Brand vs Non-Brand."*
- *"Fetch my top 5 pages by impressions and run `pagespeed_analyze` — any correlation with declining rankings?"*
- *"Compare Google vs Bing performance for the last 30 days (`compare_engines`) — where is Bing winning?"*
- *"Submit my latest URLs to Google and IndexNow using `indexing_submit` with `method: "index_now"`."*
</details>
---
## 🔌 Connect your accounts
| Platform | Method | Setup |
|---|---|---|
| **Google Search Console** | OAuth (recommended) | `npx search-console-mcp setup` |
| **Google Search Console** | Service Account | Set `GOOGLE_APPLICATION_CREDENTIALS` — [details](#service-account-advanced) |
| **Bing Webmaster Tools** | API Key | `export BING_API_KEY="..."` — [get a key](https://www.bing.com/webmasters/settings/api) |
| **Google Analytics 4** | Service Account | `npx search-console-mcp setup --engine=ga4` |
| **Google AdSense** | OAuth (read-only) | `npx search-console-mcp setup --engine=adsense` — [headless servers](#headless-servers) |
Manage everything from the CLI:
```bash
npx search-console-mcp accounts list
npx search-console-mcp accounts add-site --account=you@company.com --site=example.com
npx search-console-mcp accounts remove --account=you@company.com
```
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)
<details>
<summary id="headless-servers">Headless servers (Docker, CI, VPS)</summary>
AdSense cannot use service accounts, and config files are machine-encrypted — so authorize once on any machine with a browser and transfer the grant:
```bash
# 1. On your laptop (after setup --engine=adsense):
npx search-console-mcp adsense-export
# 2. On the server (prints a ready-to-run command on step 1):
npx search-console-mcp adsense-import --token='...' --publisher-id='accounts/pub-...'
```
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.
</details>
---
## 🖥️ Run tools from the CLI
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:
```bash
# List registered tools
npx search-console-mcp run --help
# Show options for one tool
npx search-console-mcp run analytics_query --help
# Run an SEO audit with JSON output
npx search-console-mcp run seo_audit --siteUrl=https://example.com --type=quick_wins
# Print array results as CSV or a table
npx search-console-mcp run analytics_query --siteUrl=https://example.com --startDate=2026-06-01 --endDate=2026-06-30 --dimensions=date,query --format=csv
npx search-console-mcp run sites_list --engine=all --format=table
```
<details>
<summary id="service-account-advanced">Service Account setup (for servers/automation)</summary>
1. Create a service account in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Generate a JSON key
3. Add the service account email as a user in Search Console with "Full" or "Restricted" access
4. `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`
</details>
---
## 🛠 Tools (Fluent Domain Architecture)
Search Console MCP v2.0 features **7 Fluent Domain Tools** that handle all SEO, Analytics, Inspection, and Indexing operations cleanly:
| Fluent Tool | Parameters / Actions | Description |
|---|---|---|
| `sites_list` | `engine: "all" \| "google" \| "bing"` | Lists verified sites across search engines in parallel |
| `sites_manage` | `action: "add" \| "delete"`, `siteUrl`, `engine` | Adds or removes site properties |
| `accounts_manage` | `action: "list" \| "add_site" \| "remove"` | Configures multi-account profiles |
| `sitemaps_list` | `siteUrl`, `feedUrl`, `engine` | Fetches sitemap status and indexing state |
| `sitemaps_submit` | `siteUrl`, `feedUrl`, `engine` | Submits sitemaps to GSC & Bing |
| `sitemaps_delete` | `siteUrl`, `feedUrl`, `engine` | Removes sitemaps |
| `analytics_query` | `siteUrl`, `engine`, `dimensions`, `metrics` | Multi-engine search & GA4 analytics query |
| `analytics_compare` | `mode: "period_over_period" \| "trends" \| "drop_attribution"` | Analyzes period deltas, trend shifts, and drop causes |
| `analytics_anomalies`| `siteUrl`, `threshold` | Statistical detection of traffic spikes/drops |
| `inspection_inspect`| `siteUrl`, `urls`, `engine` | Google URL inspection & Bing URL info |
| `pagespeed_analyze` | `url`, `strategy`, `cwvOnly` | Core Web Vitals and PageSpeed Insights audits |
| `indexing_submit` | `urls`, `method: "standard" \| "index_now" \| "remove"` | Instantly indexes URLs via IndexNow or Google/Bing API |
| `indexing_status` | `siteUrl`, `type: "quota" \| "status"` | Checks remaining indexing quota & URL status |
| `seo_audit` | `type: "quick_wins" \| "striking_distance" \| "cannibalization" \| "low_hanging_fruit" \| "lost_queries" \| "recommendations" \| "brand_vs_nonbrand"` | Comprehensive automated SEO audits |
| `seo_keywords_research`| `keywords`, `type: "stats" \| "related" \| "traffic"` | Keyword volumes and related keyword stats |
| `site_health_check` | `siteUrl`, `level: "summary" \| "full" \| "crawl_issues"` | One-shot site performance & technical audit |
| `compare_engines` | `siteUrl` | Side-by-side Google vs Bing performance breakdown |
| `genai_query_insights` | `siteUrl`, `days`, `engine: "google" \| "bing" \| "all"`, `includePages`, `minImpressions` | Flags likely generative-AI / conversational queries (custom heuristic, no official API) |
### Google AdSense Tools
| Tool | Parameters | Description |
|---|---|---|
| `adsense_accounts` | `mode: "configured" \| "discover"`, `accountId` | Lists configured or discoverable AdSense publisher accounts |
| `adsense_report` | `dateRange`, `startDate`, `endDate`, `dimensions`, `metrics`, `orderBy`, `rowLimit`, `accountId` | Earnings, impressions, clicks, CTR & RPM with dimension breakdowns. Custom dates override `dateRange`. |
| `adsense_payments_alerts` | `accountId` | Outstanding payments and account alerts (policy issues, payment holds) |
> **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`.
<details>
<summary><strong>Backward Compatibility Notice (96+ Legacy Tools)</strong></summary>
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.
Read our complete [Backward Compatibility & Migration Guide →](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)
</details>
---
## 🔒 Security
- **OS keychain first** — tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service
- **AES-256-GCM fallback** — encrypted with a key derived from your machine's hardware ID; a stolen file is useless on another device
- **Minimal storage** — only `refresh_token` and `expiry_date` are persisted, at `mode 600`
- **Silent refresh** — tokens renew automatically in the background
---
## License
[MIT](./LICENSE) · [Contributing guide](./CONTRIBUTING.md) · [Backward Compatibility Guide](https://searchconsolemcp.saurabh.app/concepts/backward-compatibility)
<div align="center">
If this saves you a spreadsheet, consider ⭐ starring the repo.
</div>
