search-console-mcp 1.14.0 → 1.14.1

package/README.md

@@ -1,270 +1,176 @@
+<div align="center">
 
-# Search Console MCP
+# 🔍 Search Console MCP
 
-A 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.
+**Google Search Console + Bing Webmaster Tools + GA4 — in one context window.**
 
-[📚 View Documentation](https://searchconsolemcp.saurabh.app/)
-
----
+Stop exporting CSVs. Start asking your AI agent questions.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![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)
+[![Stars](https://img.shields.io/github/stars/saurabhsharma2u/search-console-mcp?style=social)](https://github.com/saurabhsharma2u/search-console-mcp/stargazers)
 
-## Why use this?
-
-### ❌ The Old, Broken Way
-*   **Data Silos**: Manually checking Google, then Bing, then GA4.
-*   **Manual Correlation**: Exporting 3 different CSVs and using VLOOKUPs to see if your #1 ranking page actually converts.
-*   **Switching Fatigue**: Logging in and out to manage multiple clients or properties.
-*   **AI Context Limits**: Uploading giant spreadsheets that hit context limits and cause model hallucinations.
+[📚 Docs](https://searchconsolemcp.saurabh.app/) · [Quick Start](#-quick-start) · [Tools](#-tools) · [Security](#-security)
 
-### ✅ The Search Console MCP Way
-*   **Platform Synergy**: **GSC + Bing + GA4** in a single context window. Stop exporting, start analyzing.
-*   **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.
-*   **Cross-Platform ROI**: Use the **Opportunity Matrix** to prioritize keywords that have high search visibility (GSC) but poor on-site engagement (GA4).
-*   **Zero-Config Multi-Account**: Connect 20+ accounts. The server automatically resolves the correct credentials for every site URL.
-
-**One Server. Three Platforms. Infinite Accounts. Actionable Intelligence.**
+</div>
 
 ---
-## 🎯 Magic Prompts
-
-Copy and paste these into your MCP client (Claude Desktop, etc.) to see the intelligence engine in action:
-
-#### 🔍 The Traffic Detective
-> "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."
-
-#### 🎯 The "Striking Distance" Hunter
-> "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."
-
-#### ⚔️ The Cannibalization Cleaner
-> "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."
-
-#### 📈 The SEO Opportunity Scoreboard
-> "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."
 
-#### 📊 The Executive Health Check
-> "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."
+## Why this exists
 
-#### ⚡ The Speed vs. Ranking Correlator
-> "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?"
+SEO data lives in three different silos. Answering one question — *"did my traffic drop because of a ranking loss or a UX issue?"* — usually means logging into three dashboards, exporting three CSVs, and doing VLOOKUPs by hand.
 
-#### 🔀 Multi-Engine Comparison
-> "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?"
+Search Console MCP puts **GSC, Bing, and GA4** behind one set of tools your AI agent can call directly, and does the SEO math (cannibalization, anomaly detection, opportunity scoring) *before* the data ever reaches your context window — so your agent gets insights, not spreadsheets.
 
-#### 🎯 Bing Opportunity Finder
-> "Show me keywords where I'm in the top 5 on Google but not ranking on Bing. These are my easy Bing wins."
-
-#### ⚠️ Google Dependency Check
-> "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."
-
-#### 💰 The ROI Prioritizer (GSC + GA4)
-> "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."
+| | Before | After |
+|---|---|---|
+| **Data** | 3 dashboards, manual exports | 1 unified context |
+| **Analysis** | Manual VLOOKUPs & pivot tables | Deterministic SEO math, done server-side |
+| **Accounts** | Constant re-login | 20+ accounts, auto-resolved per site |
+| **Insight** | Raw rows, agent guesses | Curated signals (opportunity scores, anomalies) |
 
 ---
 
-## 🔐 Authentication (Desktop Flow)
-
-Search Console MCP uses a **Secure Desktop Flow**. This provides high-security, professional grade authentication for your Google account:
-- **Multi-Account Support**: Connect multiple Google and Bing accounts. The server automatically picks the right one for each site.
-- **System Keychain Primary**: Tokens are stored in your OS's native credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
-- **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.
-- **Silent Background Refresh**: Tokens auto-refresh silently when they expire.
+## ⚡ Quick Start
 
-### 🚀 Step 1 — Initiate Login
-Run the following command to start the authorization process:
 ```bash
 npx search-console-mcp setup
 ```
 
-The CLI will:
-1. Briefly start a secure local server to handle the redirect.
-2. Open your default web browser to the Google Authorization page.
-3. Automatically fetch your email after authorization to label your credentials securely.
-
-### 🔑 Step 2 — Logout & Management
-To wipe your credentials from both the keychain and the disk:
-```bash
-# Logout of the default account
-npx search-console-mcp logout
-
-# Logout of a specific account
-npx search-console-mcp logout user@gmail.com
+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, etc.):
+
+```json
+{
+  "mcpServers": {
+    "search-console": {
+      "command": "npx",
+      "args": ["search-console-mcp"]
+    }
+  }
+}
 ```
 
----
-
-## 🔑 Alternative: Service Account (Advanced)
+Restart your client — and try one of the prompts below.
 
-For server-side environments or automated tasks where interactive login isn't possible, you can use a Google Cloud Service Account.
+---
 
-### Setup:
-1.  **Create Service Account**: Go to the [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts) and create a service account.
-2.  **Generate Key**: Click "Keys" > "Add Key" > "Create new key" (JSON). Download this file.
-3.  **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.
-4.  **Configure**: Point the server to your key file:
-    ```bash
-    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json"
-    ```
+## 💬 Try it
 
----
+Paste these straight into your agent:
 
-## 🔑 Bing Webmaster Tools (API Key)
+> **"My traffic dropped this week vs. last. Find exactly when it started and which pages are responsible."**
 
-To access Bing data, you simply need an API Key.
+> **"Find keywords for example.com ranking positions 8–15 with 1,000+ impressions — my best quick wins."**
 
-### Setup:
-1.  **Get Your API Key**: Go to [Bing Webmaster Tools Settings](https://www.bing.com/webmasters/settings/api).
-2.  **Configure**: Set the API key in your environment:
-    ```bash
-    export BING_API_KEY="your-api-key-here"
-    ```
-3.  **IndexNow**: Bing tools also support **IndexNow** for instant URL submission.
+> **"Check for keyword cannibalization — are two of my pages competing for the same query?"**
 
----
+> **"Run `opportunity_matrix` on my top 20 pages: which have high search visibility but poor on-site engagement?"**
 
-## 📊 Google Analytics 4 (GA4)
+<details>
+<summary>More example prompts</summary>
 
-Connect your GA4 properties to correlate ranking data with user behavior.
+- *"Run a full SEO health check, segmented by Brand vs Non-Brand, with 3 high-impact actions."*
+- *"Fetch my top 5 pages by impressions and run a PageSpeed audit — any correlation with declining rankings?"*
+- *"Compare Google vs Bing performance for the last 30 days — where is Bing winning?"*
+- *"Am I too dependent on Google? Flag keywords where 85%+ of clicks come from one engine."*
 
-### Setup:
-1.  **Run Setup**: `npx search-console-mcp setup --engine=ga4`
-2.  **Auth Method**: Choose **Service Account** (JSON Key). This is the recommended method for server-side integrations.
-    *   **Service Account**: You must add the service account email as a user in **GA4 Admin > Property Settings > Property Access Management**.
-3.  **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.
+</details>
 
 ---
 
-## 👥 Multi-Account Management
+## 🔌 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` |
 
-Manage multiple Google and Bing accounts from the CLI:
+Manage everything from the CLI:
 
 ```bash
-# List all connected accounts
 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
+```
 
-# Remove an account
-npx search-console-mcp accounts remove --account=marketing@company.com
+When your agent queries a site, the server auto-resolves which account owns it — no manual switching. [Multi-account docs →](https://searchconsolemcp.mintlify.app/getting-started/multi-account)
 
-# Add a site boundary to an account
-npx search-console-mcp accounts add-site --account=marketing@company.com --site=example.com
-```
+<details>
+<summary id="service-account-advanced">Service Account setup (for servers/automation)</summary>
 
-When your AI agent queries a site, the server automatically resolves which account to use. [Learn more →](https://searchconsolemcp.mintlify.app/getting-started/multi-account)
+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
 
-## 🛡️ Fort Knox Security
+40+ tools across five categories. A few flagship ones:
 
-This MCP server implements a multi-layered security architecture:
+| Tool | What it does |
+|---|---|
+| `opportunity_matrix` | Ranks pages by combining GSC visibility with GA4 engagement — where's the ROI? |
+| `seo_striking_distance` | Keywords ranking 8–15 — your fastest wins |
+| `seo_cannibalization` | Pages competing for the same query, with a recommended primary |
+| `analytics_anomalies` | Statistical traffic drop/spike detection |
+| `sites_health_check` | One-shot WoW performance + sitemap + anomaly check |
+| `compare_engines` | Google vs Bing performance, side by side |
 
-*   **Keychain Integration**: Primarily uses the **macOS Keychain**, **Windows Credential Manager**, or **libsecret (Linux)** to store tokens.
-*   **Encrypted Config**: Account configuration is stored in `~/.search-console-mcp-config.enc` using **AES-256-GCM** encryption.
-*   **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.
-*   **Minimalist Storage**: Only the `refresh_token` and `expiry_date` are stored.
-*   **Legacy Support**: Automatically detects credentials from older versions (tokens files, environment variables).
-*   **Strict Unix Permissions**: Config files are created with `mode 600` (read/write only by your user).
+<details>
+<summary><strong>Full tool reference (40+ tools)</strong></summary>
 
----
+### Analytics & Trends
+`analytics_query` · `analytics_trends` · `analytics_anomalies` · `analytics_drop_attribution` · `analytics_time_series` · `analytics_compare_periods` · `seo_brand_vs_nonbrand`
 
-## Tools Reference
-
-### Google Analytics
-| Tool | Description |
-|------|-------------|
-| `analytics_query` | Master tool for raw data. Supports `dimensions`, `filters`, `aggregationType` (byPage/byProperty), `dataState` (final/all), and `type` (web/image/news/discover). |
-| `analytics_trends` | Detect trends (rising/falling) for specific queries or pages. |
-| `analytics_anomalies` | Detect statistical anomalies in daily traffic. |
-| `analytics_drop_attribution` | **[NEW]** Attribute traffic drops to mobile/desktop or correlate with known Google Algorithm Updates. |
-| `analytics_time_series` | **[NEW]** Advanced time series with rolling averages, seasonality detection, and forecasting. |
-| `analytics_compare_periods` | Compare two date ranges (e.g., WoW, MoM). |
-| `seo_brand_vs_nonbrand` | **[NEW]** Analyze performance split between Brand vs Non-Brand traffic. (Supports Google & Bing). |
-
-### SEO Opportunities (Opinionated)
-| Tool | Description |
-|------|-------------|
-| `seo_low_hanging_fruit` | Find keywords ranking in pos 5-20 with high impressions. |
-| `seo_striking_distance` | **[NEW]** Find keywords ranking 8-15 (Quickest ROI wins). |
-| `seo_low_ctr_opportunities` | **[NEW]** Find top ranking queries (pos 1-10) with poor CTR. |
-| `seo_cannibalization` | **[Enhanced]** Detect pages competing for the same query with traffic conflict. |
-| `seo_lost_queries` | **[NEW]** Identify queries that lost all traffic in the last 28 days. (Supports Google & Bing). |
-
-### SEO Primitives (Atoms for Agents)
-These are low-level tools designed to be used by other AI agents to build complex logic.
-| Tool | Description |
-|------|-------------|
-| `seo_primitive_ranking_bucket` | Categorize a position (e.g. "Top 3", "Page 1", "Unranked"). |
-| `seo_primitive_traffic_delta` | Calculate absolute and % change between two numbers. |
-| `seo_primitive_is_brand` | Check if a query matches a brand regex. |
-| `seo_primitive_is_cannibalized` | Check if two pages are competing for the same query. |
+### SEO Opportunities
+`seo_low_hanging_fruit` · `seo_striking_distance` · `seo_low_ctr_opportunities` · `seo_cannibalization` · `seo_lost_queries`
+
+### SEO Primitives (building blocks for agent logic)
+`seo_primitive_ranking_bucket` · `seo_primitive_traffic_delta` · `seo_primitive_is_brand` · `seo_primitive_is_cannibalized`
 
 ### Sites & Sitemaps
-| Tool | Description |
-|------|-------------|
-| `sites_list` | List all verified sites. |
-| `sites_add` / `sites_delete` | Manage properties. |
-| `sites_health_check` | **[NEW]** Run a health check on one or all sites. Checks WoW performance, sitemaps, and anomalies. |
-| `sitemaps_list` / `sitemaps_submit` | Manage sitemaps. |
+`sites_list` · `sites_add` · `sites_delete` · `sites_health_check` · `sitemaps_list` · `sitemaps_submit`
 
 ### Inspection & Validation
-| Tool | Description |
-|------|-------------|
-| `inspection_inspect` | Google URL Inspection API (Index status, mobile usability). |
-| `pagespeed_analyze` | Lighthouse scores & Core Web Vitals. |
-| `schema_validate` | Validate Structured Data (JSON-LD). |
-
-### URL Indexing (Google & Bing)
-| Tool | Description |
-|------|-------------|
-| `indexing_submit_url` | **[NEW]** Submit a URL for indexing (supports Google Indexing API and Bing URL Submission API). |
-| `indexing_remove_url` | **[NEW]** Notify Google that a URL has been removed (Google only). |
-| `indexing_status` | **[NEW]** Check notification status for a submitted URL (Google only). |
-| `indexing_batch_submit` | **[NEW]** Batch submit multiple URLs for indexing (concurrency-controlled). |
-| `bing_url_submission_quota` | Check remaining daily/monthly URL submission quota for Bing. |
+`inspection_inspect` · `pagespeed_analyze` · `schema_validate`
+
+### URL Indexing
+`indexing_submit_url` · `indexing_remove_url` · `indexing_status` · `indexing_batch_submit` · `bing_url_submission_quota`
 
 ### Bing Webmaster Tools
-| Tool | Description |
-|------|-------------|
-| `bing_sites_list` | List all verified sites in Bing. |
-| `bing_analytics_query` | Query search performance from Bing. |
-| `bing_opportunity_finder` | Find low-hanging fruit keywords on Bing. |
-| `bing_seo_recommendations` | Get prioritized SEO insights for Bing. |
-| `bing_url_info` | Detailed indexing and crawl info for a URL (Bing). |
-| `bing_index_now` | **[NEW]** Instantly notify search engines of changes. |
-| `bing_crawl_issues` | List crawl issues detected by Bing. |
-| `bing_analytics_detect_anomalies` | Detect daily spikes or drops in Bing traffic. |
-| `bing_analytics_time_series` | Advanced time series analysis for Bing. |
-| `bing_seo_lost_queries` | Identify queries that lost significant traffic on Bing. |
-| `bing_brand_analysis` | Analyze performance split between Brand vs Non-Brand traffic on Bing. |
-| `bing_sitemaps_list` / `bing_sitemaps_submit` | Manage sitemaps in Bing. |
-
-### Google Analytics 4 (GA4)
-| Tool | Description |
-|------|-------------|
-| `analytics_page_performance` | Detailed page metrics (sessions, engagement, views). |
-| `analytics_traffic_sources` | Analyze sessions by Channel, Source, and Medium. |
-| `analytics_organic_landing_pages` | Focused metrics for organic traffic landing pages. |
-| `analytics_content_performance` | Analyze content performance by Content Group in GA4. |
-| `analytics_conversion_funnel` | Top converting pages and events. |
-| `analytics_user_behavior` | Device, Country, and Engagement breakdown. |
-| `analytics_audience_segments` | New vs Returning, Age, and OS analysis. |
-| `analytics_realtime` | Live active user data by page and location. |
-| `analytics_ecommerce` | Product and revenue performance. |
-| `analytics_pagespeed_correlation` | Correlate GA4 metrics with PageSpeed scores. |
+`bing_sites_list` · `bing_analytics_query` · `bing_opportunity_finder` · `bing_seo_recommendations` · `bing_url_info` · `bing_index_now` · `bing_crawl_issues` · `bing_analytics_detect_anomalies` · `bing_analytics_time_series` · `bing_seo_lost_queries` · `bing_brand_analysis` · `bing_sitemaps_list` · `bing_sitemaps_submit`
+
+### Google Analytics 4
+`analytics_page_performance` · `analytics_traffic_sources` · `analytics_organic_landing_pages` · `analytics_content_performance` · `analytics_conversion_funnel` · `analytics_user_behavior` · `analytics_audience_segments` · `analytics_realtime` · `analytics_ecommerce` · `analytics_pagespeed_correlation`
 
 ### Cross-Platform Intelligence
-| Tool | Description |
-|------|-------------|
-| `opportunity_matrix` | **[Flagship]** Prioritize SEO tasks by combining signals from GSC, GA4, and Bing. |
-| `page_analysis` | Joint analysis of ranking (GSC) vs behavior (GA4) for pages. |
-| `traffic_health_check` | Diagnose tracking gaps by comparing GSC clicks to GA4 organic sessions. |
-| `brand_analysis` | Brand vs Non-Brand split across GSC, Bing, and GA4. |
-| `compare_engines` | Compare keyword performance between Google and Bing. |
+`opportunity_matrix` · `page_analysis` · `traffic_health_check` · `brand_analysis` · `compare_engines`
+
+</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](CONTRIBUTING.md)
+[MIT](./LICENSE) · [Contributing guide](./CONTRIBUTING.md)
+
+<div align="center">
+
+If this saves you a spreadsheet, consider ⭐ starring the repo.
+
+</div>

package/dist/google/docs/algorithm-updates.js

@@ -8,6 +8,10 @@ The \`analytics_drop_attribution\` tool correlates traffic drops with major know
 | Date | Update Name | Impact Area |
 |------|-------------|-------------|
 | 2026-02-05 | February 2026 Discover Core Update | Discover Feed |
+| 2026-03-24 | March 2026 Spam Update | Spam / Content Quality |
+| 2026-03-27 | March 2026 Core Update | General Ranking |
+| 2026-05-21 | May 2026 Core Update | General Ranking |
+| 2026-06-24 | June 2026 Spam Update | Spam / Content Quality |
 
 ## 2025
 

package/dist/google/tools/advanced-analytics.js

@@ -35,6 +35,10 @@ const ALGORITHM_UPDATES = [
     { date: '2025-12-11', name: 'December 2025 Core Update' },
     // 2026
     { date: '2026-02-05', name: 'February 2026 Discover Core Update' },
+    { date: '2026-03-24', name: 'March 2026 Spam Update' },
+    { date: '2026-03-27', name: 'March 2026 Core Update' },
+    { date: '2026-05-21', name: 'May 2026 Core Update' },
+    { date: '2026-06-24', name: 'June 2026 Spam Update' },
 ];
 /**
  * Identify the cause of a significant traffic drop by analyzing device distribution and algorithm updates.

package/dist/google/tools/pagespeed.js

@@ -1,5 +1,12 @@
 import { google } from 'googleapis';
 const pagespeed = google.pagespeedonline('v5');
+/**
+ * Returns the PageSpeed API key from environment, if configured.
+ * When set, this increases the daily quota from ~100 to 25,000 queries/day.
+ */
+function getApiKey() {
+    return process.env.PAGESPEED_API_KEY || undefined;
+}
 /**
  * Run a full PageSpeed Insights analysis on a URL.
  *
@@ -8,11 +15,25 @@ const pagespeed = google.pagespeedonline('v5');
  * @returns Performance, accessibility, and SEO scores along with field/lab metrics.
  */
 export async function analyzePageSpeed(url, strategy = 'mobile') {
-    const res = await pagespeed.pagespeedapi.runpagespeed({
-        url,
-        strategy,
-        category: ['performance', 'accessibility', 'best-practices', 'seo']
-    });
+    const key = getApiKey();
+    let res;
+    try {
+        res = await pagespeed.pagespeedapi.runpagespeed({
+            url,
+            strategy,
+            category: ['performance', 'accessibility', 'best-practices', 'seo'],
+            ...(key && { key })
+        });
+    }
+    catch (error) {
+        const status = error?.code || error?.response?.status;
+        if ((status === 429 || status === 500) && !key) {
+            throw new Error(`PageSpeed Insights rate limit exceeded. You are using the free tier which is limited to ~100 queries/day. ` +
+                `To increase your quota to 25,000/day, set the PAGESPEED_API_KEY environment variable. ` +
+                `Get a free key at: https://console.cloud.google.com/apis/credentials`);
+        }
+        throw error;
+    }
     const data = res.data;
     const lighthouse = data.lighthouseResult;
     const categories = lighthouse?.categories;

package/dist/setup.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import 'dotenv/config';
-import { readFileSync, existsSync, statSync } from 'fs';
+import { readFileSync, existsSync, statSync, writeFileSync } from 'fs';
 import { resolve, dirname, extname } from 'path';
 import { createInterface } from 'readline';
 import { homedir } from 'os';
@@ -93,19 +93,22 @@ async function detectConfig() {
         googleAccounts: accounts.filter(a => a.engine === 'google'),
         bingAccounts: accounts.filter(a => a.engine === 'bing'),
         ga4Accounts: accounts.filter(a => a.engine === 'ga4'),
-        legacyBing: !!process.env.BING_API_KEY
+        legacyBing: !!process.env.BING_API_KEY,
+        pagespeedApiKey: !!process.env.PAGESPEED_API_KEY
     };
 }
 function printDetectionSummary(results) {
     const gCount = results.googleAccounts ? results.googleAccounts.length : 0;
     const bCount = (results.bingAccounts ? results.bingAccounts.length : 0) + (results.legacyBing ? 1 : 0);
     const ga4Count = results.ga4Accounts ? results.ga4Accounts.length : 0;
-    if (gCount === 0 && bCount === 0 && ga4Count === 0)
+    const hasPageSpeed = !!results.pagespeedApiKey;
+    if (gCount === 0 && bCount === 0 && ga4Count === 0 && !hasPageSpeed)
         return;
     console.log(`${colors.bold}${colors.dim}🔍 Connection Status${colors.reset}\n`);
     printStatusLine('Google Search Console', gCount > 0);
     printStatusLine('Google Analytics 4', ga4Count > 0);
     printStatusLine('Bing Webmaster Tools', bCount > 0);
+    printStatusLine('PageSpeed Insights (API Key)', hasPageSpeed);
     console.log('');
 }
 export function validateKeyFile(path) {
@@ -532,6 +535,10 @@ export async function main() {
         await handleGA4Flow(configStatus);
         return;
     }
+    else if (engineFlag === 'pagespeed') {
+        await setupPageSpeed();
+        return;
+    }
     while (true) {
         printHeader();
         printDetectionSummary(configStatus);
@@ -539,8 +546,9 @@ export async function main() {
         console.log(`\n1. Google Search Console`);
         console.log('2. Google Analytics 4');
         console.log('3. Bing Webmaster Tools');
-        console.log('4. Exit');
-        const choice = await ask(`\n${colors.bold}${colors.cyan}Enter your choice (1-4): ${colors.reset}`);
+        console.log('4. PageSpeed Insights (Optional API Key)');
+        console.log('5. Exit');
+        const choice = await ask(`\n${colors.bold}${colors.cyan}Enter your choice (1-5): ${colors.reset}`);
         switch (choice) {
             case '1':
                 await handleGoogleFlow(configStatus, true);
@@ -552,6 +560,11 @@ export async function main() {
                 await handleBingFlow(configStatus);
                 break;
             case '4':
+                await setupPageSpeed();
+                // Refresh config status after setting key
+                Object.assign(configStatus, await detectConfig());
+                break;
+            case '5':
             default:
                 console.log(`\n${colors.dim}See you on the flip side!${colors.reset}`);
                 rl.close();
@@ -726,6 +739,55 @@ async function setupGA4OAuth() {
         printError(`Failed: ${e.message}`);
     }
 }
+async function setupPageSpeed() {
+    printBoxHeader('PageSpeed Insights Setup');
+    console.log('This key is optional, but raises daily quota from ~100 to 25,000 queries/day.');
+    console.log('1. Go to https://console.cloud.google.com/apis/credentials');
+    console.log('2. Create an API key and enable the "PageSpeed Insights API" in your project.\n');
+    const apiKey = await ask('Enter your PageSpeed API Key (leave empty to skip): ');
+    if (!apiKey) {
+        printInfo('PageSpeed setup skipped or cleared.');
+        return;
+    }
+    const envPath = resolve('.env');
+    let envContent = '';
+    if (existsSync(envPath)) {
+        envContent = readFileSync(envPath, 'utf8');
+        if (envContent.includes('PAGESPEED_API_KEY=')) {
+            // Replace existing line
+            envContent = envContent.replace(/PAGESPEED_API_KEY=.*/, `PAGESPEED_API_KEY=${apiKey}`);
+        }
+        else {
+            // Append
+            envContent += `\nPAGESPEED_API_KEY=${apiKey}\n`;
+        }
+    }
+    else {
+        const examplePath = resolve('.env.example');
+        if (existsSync(examplePath)) {
+            envContent = readFileSync(examplePath, 'utf8');
+            if (envContent.includes('PAGESPEED_API_KEY=')) {
+                envContent = envContent.replace(/PAGESPEED_API_KEY=.*/, `PAGESPEED_API_KEY=${apiKey}`);
+            }
+            else {
+                envContent += `\nPAGESPEED_API_KEY=${apiKey}\n`;
+            }
+        }
+        else {
+            envContent = `PAGESPEED_API_KEY=${apiKey}\n`;
+        }
+    }
+    writeFileSync(envPath, envContent, 'utf8');
+    printSuccess('Successfully wrote PAGESPEED_API_KEY to .env file!');
+    console.log(`\n${colors.bold}Note for MCP Client integration:${colors.reset}`);
+    console.log('If you run this server via an MCP Client (like Cursor, Claude Desktop, VS Code),');
+    console.log('you must configure the environment variables in your client\'s config file.');
+    console.log('See the documentation for more details:');
+    console.log(`${colors.cyan}https://github.com/saurabhsharma2u/search-console-mcp#pagespeed-insights-optional-api-key${colors.reset}\n`);
+    // Force reloading of env vars for current process
+    process.env.PAGESPEED_API_KEY = apiKey;
+    await ask('Press Enter to continue...');
+}
 const isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
 if (isMain) {
     main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "search-console-mcp",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "mcpName": "io.github.saurabhsharma2u/search-console-mcp",
   "description": "MCP server for Google Search Console, Bing Webmaster Tools, and Google Analytics 4",
   "type": "module",
@@ -22,7 +22,7 @@
     "google analytics",
     "ga4"
   ],
-  "author": "",
+  "author": "Saurabh Sharma",
   "license": "MIT",
   "dependencies": {
     "@adobe/structured-data-validator": "^1.7.0",