DOCSEARCHbyAlgolia
Submit Docs

Search Console MCP

repository·main·Indexed 42 days ago

https://github.com/saurabhsharma2u/search-console-mcp

A Model Context Protocol (MCP) server and CLI that unifies data from Google Search Console, Bing Webmaster Tools, Google Analytics 4, and Google AdSense. Version 2.1.3 provides AI agents and developers with tools for SEO audits, analytics queries, URL inspection, indexing management, and revenue analysis through a Fluent Domain Architecture.

Tokens
45.8K
Snippets
129
Records
212
Agent score
54%

What's inside Search Console MCP

  1. Overview of Search Console MCP

    main

    Search Console MCP is a Model Context Protocol (MCP) server that acts as a bridge between SEO performance data and AI agents. It provides deterministic tools for complex SEO calculations, preventing LLM hallucinations by performing calculations (like averages, trends, and anomaly detection) before the model reasons over the data.

    Supported data sources include:

    • Google Search Console
    • Bing Webmaster Tools
    • Google Analytics 4 (GA4)
    • Google AdSense (v2.1.0+)

    The server supports multi-engine and multi-account configurations, allowing agents to compare performance across platforms (e.g., Google vs. Bing) and manage multiple properties simultaneously.

  2. Security and Token Storage

    main

    The project implements a multi-layered security approach for storing sensitive tokens:

    1. OS Keychain First: It attempts to use native secure storage like macOS Keychain, Windows Credential Manager, or Linux Secret Service.
    2. AES-256-GCM Fallback: If native keychain is unavailable, it uses AES-256-GCM encryption with a key derived from the machine's hardware ID. This ensures that encrypted files cannot be used on a different device.
    3. Minimal Persistence: Only refresh_token and expiry_date are stored, and they are saved with mode 600 permissions.
    4. Silent Refresh: Tokens are automatically renewed in the background to maintain access without user intervention.

  3. Understanding the difference between traditional SEO and Agentic SEO via MCP

    main

    Traditional SEO tools are designed for human consumption, providing dashboards, charts, and spreadsheets that require manual interpretation.

    Agentic SEO via the Model Context Protocol (MCP) shifts the workflow from manual observation to automated reasoning. Instead of a human noticing a trend in a chart, an agent uses MCP tools to:

    1. Request specific insights (e.g., "detect anomalies").
    2. Execute mathematical checks (e.g., Z-score, standard deviation) via the MCP server.
    3. Receive structured reports.
    4. Reason about the underlying causes based on the returned data.

    This approach allows for handling scale (e.g., checking 10,000 pages for cannibalization), reducing LLM hallucinations by offloading math to the TypeScript-based server, and correlating data across siloed platforms like GSC, Bing, and GA4.

  4. How Search Console MCP architecture works

    main

    Search Console MCP acts as an intelligence layer between an MCP AI Client (like Claude Desktop, Cursor, or AGY CLI) and various search engine APIs (Google Search Console, Bing Webmaster Tools, GA4, and PageSpeed Insights).

    It uses a dual-path execution model:

    1. Fluent Tool Calls: Modern, domain-grouped operations routed through the src/tools/fluent/ subsystem.
    2. Legacy Fallback Calls: Older tool names are intercepted by a Fallback Router which delegates them to the modern Fluent handlers to ensure backward compatibility.

    Multi-engine queries (e.g., requesting data from both GSC and Bing) are handled by a Parallel Execution Engine that runs requests concurrently using Promise.allSettled. This ensures that if one engine fails or times out, the other engines still return data, reducing overall latency by over 50%.

  5. Compare performance across Google and Bing with compare_engines

    main

    The compare_engines and opportunity_matrix tools allow you to perform side-by-side performance analysis across Google, Bing, and GA4. The tool normalizes data from Google Search Console and Bing Webmaster Tools to show differences in Clicks, impressions, CTR, and position for specific keywords or pages. It also calculates Deltas (differences in position and CTR) and provides automatic Signals to highlight SEO opportunities and risks.

    Note: This tool is invoked via an AI agent using the following parameters:

- `siteUrl` (Required): Your site URL (e.g., `example.com`)
- `dimension` (Optional): The granularity of comparison. Options: `query`, `page`, `country`, or `device`. Default: `query`
- `startDate` (Optional): Start date in `YYYY-MM-DD` format. Default: 28 days ago
- `endDate` (Optional): End date in `YYYY-MM-DD` format. Default: today
- `minImpressions` (Optional): Filter for results with at least this many impressions
- `minClicks` (Optional): Filter for results with at least this many clicks

  6. Access AdSense MCP resources and prompts

    main

    The integration exposes native MCP resources and guided prompts for AI agents:

    Resources

    • seo://adsense/accounts: Configured publisher accounts.
    • seo://adsense/payments: Live balances and alerts for every configured account, keyed by account ID.

    Prompts

    • adsense_earnings_review: A guided prompt for reviewing daily trends, top domains, balances, and alerts.
    • adsense_monetization_audit: A prompt designed to identify underperforming ad units and gaps in RPM across geography or platform.

  7. Security and Privacy design in Search Console MCP

    main

    The project is designed with a focus on local control and data privacy:

    • Local Execution: The server runs locally on your machine. API keys and search data are never transmitted to third-party tracking servers.
    • Encrypted Token Vault: Credentials are stored using system-native Keychains (macOS Keychain, Windows Credential Manager). If unavailable, it falls back to AES-256-GCM hardware-bound file encryption.
    • Deterministic Calculations: Complex SEO math (such as cannibalization scores, standard deviations, and moving averages) is calculated deterministically on the server. This ensures the LLM receives cleaned, processed results rather than raw data that requires heavy reasoning.

  8. How the server selects accounts automatically

    main

    The server uses an automatic selection mechanism to handle multiple accounts. When an AI agent makes a request for a specific site, the server identifies which connected account has permission for that site.

    Key behaviors:

    • Site-specific matching: The server matches the requested domain to the account containing that site.
    • Catch-all accounts: If an account is configured to access "All Sites", it will be used if no other specific site-matching account is found.
    • Zero configuration for agents: You do not need to instruct your AI agent to use a specific account; the selection is transparent to the agent.

  9. Permissions and Data Privacy in Search Console MCP

    main

    Search Console MCP operates with read-only access to your connected accounts. It does not modify, delete, or share your data, and no data is sent to third-party servers; the tool runs locally and communicates directly with Google and Microsoft APIs.

    Requested Scopes

    ServiceScopePurpose
    Google Search Consolewebmasters.readonlyRead search performance, indexing status, and sitemap data
    Google Analytics 4analytics.readonlyRead traffic and engagement reports
    Google AdSenseadsense.readonlyRead ad revenue and performance reports
    Bing Webmaster ToolsAPI keyRead search performance data

    Security & Privacy

    • Local Storage: Credentials are stored locally on your device (using the OS keychain where available).
    • Revocation: You can revoke access at any time via your Google Account permissions page.

  11. Data handling and privacy guarantees

    main

    Search Console MCP operates as a local CLI application with the following privacy characteristics:

    • No Backend: The application does not operate a backend server.
    • No Data Transmission: User data is never transmitted to the developer.
    • No Analytics: The application does not collect analytics about user data.
    • Direct Communication: All API communication occurs directly between your local device and the Google or Bing APIs.

  12. Backward compatibility for legacy site and sitemap tools

    main

    The project maintains 100% backward compatibility for legacy site and sitemap tools via a fallback router. If your agent or integration uses older tool names, they will still function.

    Supported Legacy Tools:

    • sites_list (Legacy)
    • bing_sites_list
    • sites_add
    • sites_delete
    • sitemaps_list
    • bing_sitemaps_list
    • sitemaps_get
    • sitemaps_submit
    • sitemaps_delete