Search Console MCP

1 
2# Search Console MCP
3 
4A Model Context Protocol (MCP) server that transforms how you interact with **Google Search Console**, **Bing Webmaster Tools**, and **Google Analytics 4**. Stop exporting CSVs and start asking questions.
5 
6[📚 View Documentation](https://searchconsolemcp.mintlify.app/)
7 
8---
9 
10[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11[![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)
12 
13## Why use this?
14 
15### ❌ The Old, Broken Way
16*   **Data Silos**: Manually checking Google, then Bing, then GA4.
17*   **Manual Correlation**: Exporting 3 different CSVs and using VLOOKUPs to see if your #1 ranking page actually converts.
18*   **Switching Fatigue**: Logging in and out to manage multiple clients or properties.
19*   **AI Context Limits**: Uploading giant spreadsheets that hit context limits and cause model hallucinations.
20 
21### ✅ The Search Console MCP Way
22*   **Platform Synergy**: **GSC + Bing + GA4** in a single context window. Stop exporting, start analyzing.
23*   **Deterministic Intelligence**: The server performs the complex SEO math (cannibalization, Z-score anomalies, striking distance) so your AI agent gets curated insights, not raw data piles.
24*   **Cross-Platform ROI**: Use the **Opportunity Matrix** to prioritize keywords that have high search visibility (GSC) but poor on-site engagement (GA4).
25*   **Zero-Config Multi-Account**: Connect 20+ accounts. The server automatically resolves the correct credentials for every site URL.
26 
27**One Server. Three Platforms. Infinite Accounts. Actionable Intelligence.**
28 
29---
30## 🎯 Magic Prompts
31 
32Copy and paste these into your MCP client (Claude Desktop, etc.) to see the intelligence engine in action:
33 
34#### 🔍 The Traffic Detective
35> "My traffic dropped this week compared to last. Use the anomaly detection and time-series tools to find exactly when the drop started and which pages are responsible."
36 
37#### 🎯 The "Striking Distance" Hunter
38> "Find keywords for https://example.com where I'm ranking in positions 8-15 but have at least 1,000 impressions. These are my best opportunities for a quick traffic boost."
39 
40#### ⚔️ The Cannibalization Cleaner
41> "Check for keyword cannibalization. Are there any queries where two or more of my pages are competing and splitting the traffic? Suggest which one should be the primary authority."
42 
43#### 📈 The SEO Opportunity Scoreboard
44> "Analyze my top 50 keywords for the last 90 days. Rank them by a custom 'Opportunity Score' (Impressions / Position). Give me the top 5 specific pages to focus on."
45 
46#### 📊 The Executive Health Check
47> "Run a full SEO health check for my site. Segment the results by Brand vs. Non-Brand and give me 3 high-impact actions for the upcoming week."
48 
49#### ⚡ The Speed vs. Ranking Correlator
50> "Fetch the top 5 pages by impressions. For these pages, run a PageSpeed audit. Is there any correlation between low performance scores and recently declining positions?"
51 
52#### 🔀 Multi-Engine Comparison
53> "Compare my performance between Google and Bing for the last 30 days. Which keywords are ranking better on Bing but have lower traffic on Google?"
54 
55#### 🎯 Bing Opportunity Finder
56> "Show me keywords where I'm in the top 5 on Google but not ranking on Bing. These are my easy Bing wins."
57 
58#### ⚠️ Google Dependency Check
59> "Am I too dependent on Google? Check my click share across both engines and flag any keywords where over 85% of traffic comes from Google."
60 
61#### 💰 The ROI Prioritizer (GSC + GA4)
62> "Run an `opportunity_matrix` for my top 20 pages. Which high-visibility pages have the lowest engagement or conversion rates? These are my conversion optimization priorities."
63 
64---
65 
66## 🔐 Authentication (Desktop Flow)
67 
68Search Console MCP uses a **Secure Desktop Flow**. This provides high-security, professional grade authentication for your Google account:
69- **Multi-Account Support**: Connect multiple Google and Bing accounts. The server automatically picks the right one for each site.
70- **System Keychain Primary**: Tokens are stored in your OS's native credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
71- **AES-256-GCM Hardware-Bound Encryption**: Fallback storage is encrypted with AES-256-GCM using a key derived from your unique hardware machine ID. Tokens stolen from your machine cannot be decrypted on another computer.
72- **Silent Background Refresh**: Tokens auto-refresh silently when they expire.
73 
74### 🚀 Step 1 — Initiate Login
75Run the following command to start the authorization process:
76```bash
77npx search-console-mcp setup
78```
79 
80The CLI will:
811. Briefly start a secure local server to handle the redirect.
822. Open your default web browser to the Google Authorization page.
833. Automatically fetch your email after authorization to label your credentials securely.
84 
85### 🔑 Step 2 — Logout & Management
86To wipe your credentials from both the keychain and the disk:
87```bash
88# Logout of the default account
89npx search-console-mcp logout
90 
91# Logout of a specific account
92npx search-console-mcp logout user@gmail.com
93```
94 
95---
96 
97## 🔑 Alternative: Service Account (Advanced)
98 
99For server-side environments or automated tasks where interactive login isn't possible, you can use a Google Cloud Service Account.
100 
101### Setup:
1021.  **Create Service Account**: Go to the [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts) and create a service account.
1032.  **Generate Key**: Click "Keys" > "Add Key" > "Create new key" (JSON). Download this file.
1043.  **Share Access**: In Google Search Console, add the service account's email address (e.g., `account@project.iam.gserviceaccount.com`) as a user with at least "Full" or "Restricted" permissions.
1054.  **Configure**: Point the server to your key file:
106    ```bash
107    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json"
108    ```
109 
110---
111 
112## 🔑 Bing Webmaster Tools (API Key)
113 
114To access Bing data, you simply need an API Key.
115 
116### Setup:
1171.  **Get Your API Key**: Go to [Bing Webmaster Tools Settings](https://www.bing.com/webmasters/settings/api).
1182.  **Configure**: Set the API key in your environment:
119    ```bash
120    export BING_API_KEY="your-api-key-here"
121    ```
1223.  **IndexNow**: Bing tools also support **IndexNow** for instant URL submission.
123 
124---
125 
126## 📊 Google Analytics 4 (GA4)
127 
128Connect your GA4 properties to correlate ranking data with user behavior.
129 
130### Setup:
1311.  **Run Setup**: `npx search-console-mcp setup --engine=ga4`
1322.  **Auth Method**: Choose **Service Account** (JSON Key). This is the recommended method for server-side integrations.
133    *   **Service Account**: You must add the service account email as a user in **GA4 Admin > Property Settings > Property Access Management**.
1343.  **Property Selection**: The tool will automatically fetch all available GA4 properties for your account and let you select one from a list. You can also enter a Property ID manually if needed.
135 
136---
137 
138## 👥 Multi-Account Management
139 
140Manage multiple Google and Bing accounts from the CLI:
141 
142```bash
143# List all connected accounts
144npx search-console-mcp accounts list
145 
146# Remove an account
147npx search-console-mcp accounts remove --account=marketing@company.com
148 
149# Add a site boundary to an account
150npx search-console-mcp accounts add-site --account=marketing@company.com --site=example.com
151```
152 
153When your AI agent queries a site, the server automatically resolves which account to use. [Learn more →](https://searchconsolemcp.mintlify.app/getting-started/multi-account)
154 
155---
156 
157 
158## 🛡️ Fort Knox Security
159 
160This MCP server implements a multi-layered security architecture:
161 
162*   **Keychain Integration**: Primarily uses the **macOS Keychain**, **Windows Credential Manager**, or **libsecret (Linux)** to store tokens.
163*   **Encrypted Config**: Account configuration is stored in `~/.search-console-mcp-config.enc` using **AES-256-GCM** encryption.
164*   **Machine Fingerprinting**: The encryption key is derived from your unique hardware UUID and OS user. The encrypted file is useless if moved to another machine.
165*   **Minimalist Storage**: Only the `refresh_token` and `expiry_date` are stored.
166*   **Legacy Support**: Automatically detects credentials from older versions (tokens files, environment variables).
167*   **Strict Unix Permissions**: Config files are created with `mode 600` (read/write only by your user).
168 
169---
170 
171## Tools Reference
172 
173### Google Analytics
174| Tool | Description |
175|------|-------------|
176| `analytics_query` | Master tool for raw data. Supports `dimensions`, `filters`, `aggregationType` (byPage/byProperty), `dataState` (final/all), and `type` (web/image/news/discover). |
177| `analytics_trends` | Detect trends (rising/falling) for specific queries or pages. |
178| `analytics_anomalies` | Detect statistical anomalies in daily traffic. |
179| `analytics_drop_attribution` | **[NEW]** Attribute traffic drops to mobile/desktop or correlate with known Google Algorithm Updates. |
180| `analytics_time_series` | **[NEW]** Advanced time series with rolling averages, seasonality detection, and forecasting. |
181| `analytics_compare_periods` | Compare two date ranges (e.g., WoW, MoM). |
182| `seo_brand_vs_nonbrand` | **[NEW]** Analyze performance split between Brand vs Non-Brand traffic. |
183 
184### SEO Opportunities (Opinionated)
185| Tool | Description |
186|------|-------------|
187| `seo_low_hanging_fruit` | Find keywords ranking in pos 5-20 with high impressions. |
188| `seo_striking_distance` | **[NEW]** Find keywords ranking 8-15 (Quickest ROI wins). |
189| `seo_low_ctr_opportunities` | **[NEW]** Find top ranking queries (pos 1-10) with poor CTR. |
190| `seo_cannibalization` | **[Enhanced]** Detect pages competing for the same query with traffic conflict. |
191| `seo_lost_queries` | **[NEW]** Identify queries that lost all traffic in the last 28 days. |
192 
193### SEO Primitives (Atoms for Agents)
194These are low-level tools designed to be used by other AI agents to build complex logic.
195| Tool | Description |
196|------|-------------|
197| `seo_primitive_ranking_bucket` | Categorize a position (e.g. "Top 3", "Page 1", "Unranked"). |
198| `seo_primitive_traffic_delta` | Calculate absolute and % change between two numbers. |
199| `seo_primitive_is_brand` | Check if a query matches a brand regex. |
200| `seo_primitive_is_cannibalized` | Check if two pages are competing for the same query. |
201 
202### Sites & Sitemaps
203| Tool | Description |
204|------|-------------|
205| `sites_list` | List all verified sites. |
206| `sites_add` / `sites_delete` | Manage properties. |
207| `sites_health_check` | **[NEW]** Run a health check on one or all sites. Checks WoW performance, sitemaps, and anomalies. |
208| `sitemaps_list` / `sitemaps_submit` | Manage sitemaps. |
209 
210### Inspection & Validation
211| Tool | Description |
212|------|-------------|
213| `inspection_inspect` | Google URL Inspection API (Index status, mobile usability). |
214| `pagespeed_analyze` | Lighthouse scores & Core Web Vitals. |
215| `schema_validate` | Validate Structured Data (JSON-LD). |
216 
217### Bing Webmaster Tools
218| Tool | Description |
219|------|-------------|
220| `bing_sites_list` | List all verified sites in Bing. |
221| `bing_analytics_query` | Query search performance from Bing. |
222| `bing_opportunity_finder` | Find low-hanging fruit keywords on Bing. |
223| `bing_seo_recommendations` | Get prioritized SEO insights for Bing. |
224| `bing_url_info` | Detailed indexing and crawl info for a URL (Bing). |
225| `bing_index_now` | **[NEW]** Instantly notify search engines of changes. |
226| `bing_crawl_issues` | List crawl issues detected by Bing. |
227| `bing_analytics_detect_anomalies` | Detect daily spikes or drops in Bing traffic. |
228| `bing_analytics_time_series` | Advanced time series analysis for Bing. |
229| `bing_sitemaps_list` / `bing_sitemaps_submit` | Manage sitemaps in Bing. |
230 
231### Google Analytics 4 (GA4)
232| Tool | Description |
233|------|-------------|
234| `analytics_page_performance` | Detailed page metrics (sessions, engagement, views). |
235| `analytics_traffic_sources` | Analyze sessions by Channel, Source, and Medium. |
236| `analytics_organic_landing_pages` | Focused metrics for organic traffic landing pages. |
237| `analytics_content_performance` | Analyze content performance by Content Group in GA4. |
238| `analytics_conversion_funnel` | Top converting pages and events. |
239| `analytics_user_behavior` | Device, Country, and Engagement breakdown. |
240| `analytics_audience_segments` | New vs Returning, Age, and OS analysis. |
241| `analytics_realtime` | Live active user data by page and location. |
242| `analytics_ecommerce` | Product and revenue performance. |
243| `analytics_pagespeed_correlation` | Correlate GA4 metrics with PageSpeed scores. |
244 
245### Cross-Platform Intelligence
246| Tool | Description |
247|------|-------------|
248| `opportunity_matrix` | **[Flagship]** Prioritize SEO tasks by combining signals from GSC, GA4, and Bing. |
249| `page_analysis` | Joint analysis of ranking (GSC) vs behavior (GA4) for pages. |
250| `traffic_health_check` | Diagnose tracking gaps by comparing GSC clicks to GA4 organic sessions. |
251| `brand_analysis` | Brand vs Non-Brand split across GSC, Bing, and GA4. |
252| `compare_engines` | Compare keyword performance between Google and Bing. |
253 
254 
255 
256## License
257 
258[MIT](LICENSE)
259[Contributing](CONTRIBUTING.md)
260