# Commands Reference Source: https://searchconsolemcp.saurabh.app/cli/commands A complete guide to all search-console-mcp CLI commands. The CLI provides two categories of commands: **Interactive Admin Commands** (for configuration and authentication) and the **Tool Runner** (to run SEO intelligence tools). *** ## Interactive Admin Commands These commands manage authentication, configuration, and diagnostics. ### `setup` Starts the interactive configuration wizard to connect your Google Search Console, Bing Webmaster Tools, or Google Analytics 4 accounts. * **What it does:** Opens a browser window for secure OAuth authorization and saves credentials. * **Usage:** ```bash theme={null} npx search-console-mcp setup ``` ### `login` Triggers the OAuth login flow specifically to authorize a new account. * **Usage:** ```bash theme={null} npx search-console-mcp login ``` ### `logout` Revokes active OAuth tokens and logs out from all connected Google accounts. * **Usage:** ```bash theme={null} npx search-console-mcp logout ``` ### `accounts` Manages connected search engine accounts. * **Subcommands:** * `list`: Display all authorized Google, Bing, GA4, and AdSense accounts along with their associated sites. * `add-site`: Authorize a specific site or domain for an account. * `remove`: Remove a connected account. * **Usage:** ```bash theme={null} npx search-console-mcp accounts list npx search-console-mcp accounts remove --account=user@company.com ``` ### `sites` A quick shortcut to display all verified sites across all connected accounts. * **Usage:** ```bash theme={null} npx search-console-mcp sites ``` ### `diagnostics` Runs diagnostic checks to troubleshoot connection errors, quota limits, and API authorization status. * **Usage:** ```bash theme={null} npx search-console-mcp diagnostics ``` ### `update` Triggers an automated check and updates the `search-console-mcp` package to the latest version. * **Usage:** ```bash theme={null} npx search-console-mcp update ``` *** ## Tool Runner Command (`run`) The `run` subcommand lets you execute any registered MCP tool. ### Syntax ```bash theme={null} npx search-console-mcp run [options] [--format=json|csv|table] ``` ### Passing Arguments CLI arguments correspond directly to the properties defined in each tool's Zod schema. You can pass them in two ways: 1. **Equals sign:** `--siteUrl=https://example.com` 2. **Space separated:** `--siteUrl https://example.com` Boolean flags can be toggled on by passing `--flag` or turned off using `--no-flag` (e.g. `--no-enabled`). ### Formatting Results Renders tool outputs in your preferred layout: ```bash theme={null} # Print as CSV npx search-console-mcp run sites_list --engine=google --format=csv # Print as a clean ASCII table npx search-console-mcp run seo_striking_distance --siteUrl=https://example.com --format=table ``` ### Finding Tool Names & Options You can list all available tools or inspect options for a single tool by appending `--help`: ```bash theme={null} # List all executable tools npx search-console-mcp run --help # Show arguments for a specific tool npx search-console-mcp run analytics_query --help ``` To see the detailed schemas and metrics returned by each tool, refer to the **Tools** section in the **MCP Server** tab. # CLI Overview Source: https://searchconsolemcp.saurabh.app/cli/overview Exposing MCP tools as first-class CLI commands. The `search-console-mcp` package isn't just an MCP server — it is also a complete Command Line Interface (CLI) tool. Every single tool registered with the MCP server can be executed directly in your terminal. ## What It Is The CLI allows you to execute SEO intelligence queries, check sitemap statuses, submit URLs for indexing, and run site diagnostics directly from your command line without needing an MCP client like Claude or Cursor. ## How It Works The CLI wraps the exact same code and Zod validation schemas used by the MCP server. When you run a tool through the CLI, it parses and validates your flags against the tool's parameters. ### Parity with MCP * **Identical Features:** Any feature available to your AI agent via MCP is available to you via the CLI. * **Strict Validation:** If a tool requires a `siteUrl` in GSC, the CLI will enforce it and reject invalid inputs. ## Output Formatting By default, CLI tools print their responses as JSON. You can customize the presentation using the `--format` flag: * **JSON (default):** Clean, structured JSON output (perfect for pipings or integrations). * **CSV:** Outputs arrays as comma-separated values (great for importing into Google Sheets or Excel). * **Table:** Renders data as a formatted ASCII grid table, making it highly readable. *** ## Next Steps * [Commands Reference](/cli/commands) — Explore all interactive subcommands and tool runners. * [Auto-Update](/cli/update) — Learn how the update prompt and manual update commands work. # Package Updates Source: https://searchconsolemcp.saurabh.app/cli/update How search-console-mcp checks for and applies version updates. To ensure you always have access to the latest SEO tools, PageSpeed metrics, and search algorithm rules, `search-console-mcp` handles updates automatically. *** ## Interactive Update Prompts When running commands directly in an interactive terminal (TTY): 1. The CLI performs a quick version check in the background. 2. If a newer version is available on npm, a notice appears: ```text theme={null} ⚠️ A new version of search-console-mcp is available: v2.0.0 (current: v1.14.2) Press Enter to update automatically, or any other key to continue... ``` 3. Pressing `Enter` automatically triggers `npm install -g search-console-mcp` to update the package, after which the CLI exits so you can restart the tool. Pressing any other key skips the update and runs your command immediately. *** ## Background Update Checking To prevent network calls from adding latency to every execution, update checks are cached locally for 24 hours. The CLI only queries the npm registry if the cached check has expired, ensuring tool runs remain fast. *** ## Manual Update Command If you want to force check and apply updates immediately, use the dedicated `update` subcommand: ```bash theme={null} npx search-console-mcp update ``` *** ## Agent-Facing Notifications When running in MCP Server mode (over standard I/O inside Claude Desktop or Cursor), displaying interactive terminal prompts is disabled to prevent breaking communication protocols. Instead, if a new version is available: * The server appends a system notice to the bottom of the tool's text response. * This notice alerts the AI agent (e.g. Claude) that a newer version is available. * The agent can then inform you during your chat session, recommending that you run the `npx search-console-mcp update` command in your terminal. # Architecture Source: https://searchconsolemcp.saurabh.app/concepts/architecture How Search Console MCP v2.0 is built. Search Console MCP v2.0 acts as a high-performance intelligence layer between your AI agent and search engine APIs (Google Search Console, Bing Webmaster Tools, Google Analytics 4, and PageSpeed Insights). ## System Architecture Overview ``` ┌─────────────────────────────────────────┐ │ MCP AI Client │ │ (Claude Desktop, Cursor, AGY CLI) │ └────────────────────┬────────────────────┘ │ JSON-RPC (MCP) ▼ ┌─────────────────────────────────────────┐ │ Search Console MCP │ │ (src/tools/fluent/*) │ └──────┬───────────────────────────┬──────┘ │ │ Fluent Tool Call Legacy Fallback Tool Call │ │ │ ┌────────┴────────┐ │ │ Fallback Router │ │ └────────┬────────┘ ▼ ▼ ┌─────────────────────────────────────────┐ │ Parallel Execution Engine (GSC/Bing) │ │ (src/common/utils/parallel.ts) │ └──────┬──────────────┬─────────────┬─────┘ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌───────────┐ ┌──────────┐ │ Google GSC │ │ Bing WMT │ │ GA4 │ └────────────┘ └───────────┘ └──────────┘ ``` *** ## Key Subsystems ### 1. Fluent Domain Architecture (`src/tools/fluent/`) Search Console MCP v2.0 groups all operations into **7 clean domain modules**: * **`sites.ts`**: Site property management & multi-account configuration (`sites_list`, `sites_manage`, `accounts_manage`). * **`sitemaps.ts`**: Sitemap listing, submission, and removal (`sitemaps_list`, `sitemaps_submit`, `sitemaps_delete`). * **`analytics.ts`**: Unified search queries, PoP comparison, trends, anomalies, and drop attribution (`analytics_query`, `analytics_compare`, `analytics_anomalies`). * **`inspection.ts`**: URL inspection & Core Web Vitals audit (`inspection_inspect`, `pagespeed_analyze`). * **`indexing.ts`**: Instant URL indexing via IndexNow or Google/Bing APIs (`indexing_submit`, `indexing_status`). * **`seo.ts`**: Automated SEO audits and keyword research (`seo_audit`, `seo_keywords_research`, `schema_validate`). * **`health.ts`**: Cross-platform health checks & engine comparison (`site_health_check`, `compare_engines`). *** ### 2. Parallel Multi-Engine Runner (`src/common/utils/parallel.ts`) Multi-engine queries (`engine: "all"`) run concurrently using `Promise.allSettled`. If one engine encounters a temporary auth issue or timeout, the remaining engines return valid data without failing the overall query. This architecture reduces multi-engine latency by **50%+**. *** ### 3. Fallback Router Layer (`src/legacy/fallback-router.ts`) To ensure **100% backward compatibility** for all \~96 legacy tool names (`bing_sites_list`, `seo_quick_wins`, `sitemaps_get`, `bing_index_now`, etc.), the Fallback Router intercepts legacy invocations and delegates them directly to the corresponding Fluent handler. [Read full Backward Compatibility Documentation →](/concepts/backward-compatibility) *** ## Security & Privacy Design * **Local Execution**: The server runs locally on your machine. Your API keys and search data are never sent to third-party tracking servers. * **Encrypted Token Vault**: Credentials are stored in system Keychains (macOS Keychain, Windows Credential Manager) with AES-256-GCM hardware-bound file encryption fallback. * **Deterministic Server-Side Calculations**: SEO math (cannibalization scores, standard deviations, moving averages) is calculated deterministically on the server before passing cleaned results to the LLM context window. # Backward compatibility Source: https://searchconsolemcp.saurabh.app/concepts/backward-compatibility # 🔄 Backward Compatibility & Migration Guide Search Console MCP has over 1,000 weekly active installs. To ensure zero disruption for existing scripts, AI agent workflows, and automation pipelines, **Search Console MCP v2.0 guarantees 100% backward compatibility**. *** ## How Backward Compatibility Works All \~96 legacy tool names (such as `bing_sites_list`, `seo_quick_wins`, `sitemaps_get`, `indexing_submit_url`, `bing_index_now`, etc.) continue to work seamlessly without throwing errors or requiring configuration changes. When an AI agent or API client calls a legacy tool name: 1. The request is intercepted by the lightweight **Fallback Router** (`src/legacy/fallback-router.ts`). 2. The router maps the legacy tool name and arguments directly to its equivalent **Fluent Domain Tool**. 3. Results are returned in the exact expected structure, silently and transparently. ``` ┌──────────────────────────────┐ │ Incoming MCP Tool Request │ └──────────────┬───────────────┘ │ Is it a Fluent Domain Tool? (e.g. sites_list) / \ / \ YES NO (Legacy Tool Name) / \ ┌───────────────────────┐ ┌─────────────────────────────┐ │ Execute Fluent Domain │ │ Pass to Fallback Router │ │ Handler (sites.ts) │ │ (legacy/fallback-router.ts) │ └───────────────────────┘ └──────────────┬──────────────┘ │ Map parameters & delegate │ ▼ ┌─────────────────────────────┐ │ Execute Target Fluent Tool │ └─────────────────────────────┘ ``` *** ## 📋 Full Legacy Tool Mapping Table Below is the complete reference table mapping all \~96 legacy tool names to their modern Fluent Domain equivalents: | Legacy Tool Name | Modern Fluent Tool Call | Notes | | :------------------------------- | :----------------------------------------------------------------------- | :------------------------------------- | | **`sites_list`** | `sites_list({ engine: "all" })` | Supports `google`, `bing`, or `all` | | **`bing_sites_list`** | `sites_list({ engine: "bing" })` | Direct Bing site listing | | **`sites_add`** | `sites_manage({ action: "add", siteUrl })` | Adds site across specified engine | | **`bing_sites_add`** | `sites_manage({ action: "add", siteUrl, engine: "bing" })` | Adds site to Bing | | **`sites_delete`** | `sites_manage({ action: "delete", siteUrl })` | Deletes site from specified engine | | **`bing_sites_delete`** | `sites_manage({ action: "delete", siteUrl, engine: "bing" })` | Deletes site from Bing | | **`accounts_list`** | `accounts_manage({ action: "list" })` | Lists configured accounts | | **`accounts_add_site`** | `accounts_manage({ action: "add_site", accountId, siteUrl })` | Adds site to account | | **`accounts_remove`** | `accounts_manage({ action: "remove", accountId })` | Removes account | | **`sitemaps_list`** | `sitemaps_list({ siteUrl })` | Lists sitemaps for site | | **`bing_sitemaps_list`** | `sitemaps_list({ siteUrl, engine: "bing" })` | Lists Bing sitemaps | | **`sitemaps_get`** | `sitemaps_list({ siteUrl, feedUrl })` | Fetches specific sitemap details | | **`sitemaps_submit`** | `sitemaps_submit({ siteUrl, feedUrl })` | Submits sitemap | | **`bing_sitemaps_submit`** | `sitemaps_submit({ siteUrl, feedUrl, engine: "bing" })` | Submits sitemap to Bing | | **`sitemaps_delete`** | `sitemaps_delete({ siteUrl, feedUrl })` | Deletes sitemap | | **`bing_sitemaps_delete`** | `sitemaps_delete({ siteUrl, feedUrl, engine: "bing" })` | Deletes Bing sitemap | | **`analytics_query`** | `analytics_query({ siteUrl, engine: "all" })` | Queries search analytics | | **`bing_analytics_query`** | `analytics_query({ siteUrl, engine: "bing" })` | Queries Bing search analytics | | **`analytics_compare_periods`** | `analytics_compare({ siteUrl, mode: "period_over_period" })` | Period-over-period comparison | | **`analytics_trends`** | `analytics_compare({ siteUrl, mode: "trends" })` | Traffic trend detection | | **`analytics_anomalies`** | `analytics_anomalies({ siteUrl })` | Statistical anomaly detection | | **`analytics_drop_attribution`** | `analytics_compare({ siteUrl, mode: "drop_attribution" })` | Traffic drop root-cause attribution | | **`inspection_inspect`** | `inspection_inspect({ siteUrl, urls })` | Google URL inspection | | **`bing_url_info`** | `inspection_inspect({ siteUrl, urls, engine: "bing" })` | Bing URL info inspection | | **`pagespeed_analyze`** | `pagespeed_analyze({ url })` | PageSpeed Insights audit | | **`pagespeed_core_web_vitals`** | `pagespeed_analyze({ url, cwvOnly: true })` | Core Web Vitals audit | | **`indexing_submit_url`** | `indexing_submit({ siteUrl, urls, method: "standard" })` | Google Indexing API submission | | **`bing_url_submit`** | `indexing_submit({ siteUrl, urls, method: "standard", engine: "bing" })` | Bing URL submission | | **`bing_index_now`** | `indexing_submit({ urls, host, key, method: "index_now" })` | IndexNow instant indexing | | **`seo_quick_wins`** | `seo_audit({ siteUrl, type: "quick_wins" })` | Striking distance queries | | **`seo_striking_distance`** | `seo_audit({ siteUrl, type: "striking_distance" })` | Queries ranking 8–15 | | **`seo_cannibalization`** | `seo_audit({ siteUrl, type: "cannibalization" })` | Cannibalization detection | | **`seo_low_hanging_fruit`** | `seo_audit({ siteUrl, type: "low_hanging_fruit" })` | High impression low CTR queries | | **`seo_lost_queries`** | `seo_audit({ siteUrl, type: "lost_queries" })` | Lost ranking queries | | **`seo_recommendations`** | `seo_audit({ siteUrl, type: "recommendations" })` | AI SEO recommendation audit | | **`seo_brand_vs_nonbrand`** | `seo_audit({ siteUrl, type: "brand_vs_nonbrand" })` | Brand vs non-brand breakdown | | **`sites_health_check`** | `site_health_check({ siteUrl })` | Full cross-platform health check | | **`compare_engines`** | `compare_engines({ siteUrl })` | Side-by-side Google vs Bing comparison | *** ## Why Migrate to Fluent Domain Tools? While legacy tool calls are fully supported indefinitely, migrating to **Fluent Domain Tools** offers key benefits: 1. **Smaller Context Footprint**: 7 clean domain tools instead of 96+ individual tools in your AI agent's schema window. 2. **Parallel Fetch (`engine: "all"`)**: Concurrently fetch Google, Bing, and GA4 data with up to **50%+ faster latency**. 3. **Structured Parameterization**: Single entry points (`seo_audit`, `analytics_query`, `indexing_submit`) accept clear `type` and `action` parameters for easier prompt writing. *** ## Verification & Guarantee Our automated test suite continuously verifies backward compatibility: * All \~96 legacy fallback mappings are tested in `tests/fluent-tools.test.ts`. * 100% of statements and branches in `src/legacy/fallback-router.ts` are covered by automated unit tests. # Data vs. Intelligence Source: https://searchconsolemcp.saurabh.app/concepts/data-vs-intelligence Why we don't just return raw API logs. Most API integrations focus on **data delivery**: handing the computer a pile of numbers. This MCP focuses on **intelligence delivery**: handing the computer a set of findings. ## The Raw Data Problem If you ask a model for keywords with "Striking Distance" (ranking 8-15) using raw data: 1. The agent calls the API. 2. It gets 5,000 keyword rows. 3. It tries to scan them. 4. It gets distracted or hits a context window limit. 5. It misses the keywords ranking at position 16. ## The Intelligence Solution If you use the `seo_striking_distance` tool: 1. The MCP server fetches the 5,000 rows. 2. It applies a strict filter: `position >= 8 && position <= 15`. 3. It sorts them by `impressions` to find the most valuable ones. 4. It returns only the top 50 relevant keywords. 5. The agent receives a curated list of high-value opportunities. ## Deterministic Primitives We categorize our tools into two types: ### 1. Data Proxies Standard tools for listing sites, sitemaps, or running basic queries. High flexibility, low intelligence. ### 2. Intelligence Primitives (The "Pro" Tools) Advanced tools that implement specific SEO logic: * **Anomaly Detection:** Uses Z-scores to find statistically significant spikes or drops. * **Trend Identification:** Compares two periods to find items with the most momentum. * **Attribution Analysis:** Breaking down *where* a drop came from (mobile vs. desktop, specific countries). By using intelligence primitives, you allow the AI agent to act like a senior SEO strategist rather than a data entry clerk. # MCP and SEO Source: https://searchconsolemcp.saurabh.app/concepts/mcp-and-seo How the Model Context Protocol changes SEO analysis. Traditional SEO tools are built for humans: dashboards, charts, and spreadsheets. **Model Context Protocol (MCP)** tools are built for agents. ## The Semantic Gap In traditional analysis: 1. A human looks at a chart. 2. The human notices a trend. 3. The human looks for an explanation. In Agentic SEO: 1. The agent asks for a specific insight (e.g., "detect anomalies"). 2. The MCP server runs a mathematical check (Z-score, standard deviation). 3. The server returns a structured report. 4. The agent reasons about the *why* based on the *what*. ## Why it Matters ### 1. Handling Scale A human can't manually check for keyword cannibalization across 10,000 pages every day. An agent with a `detect_cannibalization` tool can do it in seconds. ### 2. Reducing Hallucinations When an LLM performs math, it's prone to errors. By offloading calculation to the MCP server (written in TypeScript), we ensure the agent is reasoning with 100% accurate metrics. ### 3. Cross-Platform Correlation Standard SEO data is siloed. By combining **GSC, Bing, and GA4** in a single protocol, agents can identify correlations that humans often miss—like a ranking drop that actually *increases* revenue because it pruned low-intent traffic. ### 4. State-of-the-Art Intelligence Our MCP server doesn't just pass strings; it implements SEO primitives like: * **Ranking Buckets:** Categorizing results into 'Top 3', 'Page 1', etc. * **Traffic Deltas:** Calculating whether a change is statistically significant. * **Opportunity Scoring:** Estimating potential clicks based on impression volume. ## The Future of SEO We see a future where SEO is not about "reporting" but about "resolution." Instead of spending 4 hours on a monthly deck, you'll spend 5 minutes reviewing a summary from your SEO agent, which has already performed the deep-dive analysis using these tools. # Trust and Security Source: https://searchconsolemcp.saurabh.app/concepts/trust-and-security Safe automation for your most valuable data. Search Console data is sensitive. It reveals exactly what keywords your business depends on. We designed this MCP server with a "security-first" mindset. ## Secure Token Storage We treat your Google credentials with the highest level of security available on your operating system. * **System Keychain:** Access tokens and refresh tokens are stored primarily in your OS's native credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service). * **Hardware-Bound Encryption:** If keychain storage is unavailable, tokens are encrypted using **AES-256-GCM** with a key derived from your unique hardware machine ID. This means sophisticated malware or attackers cannot simply steal the file and use it elsewhere. * **Minimal Footprint:** We only store the `refresh_token` and `expiry_date`. No other personal information is persisted. ## Explainability Over Everything We believe agents should be able to explain *how* they reached a conclusion. * **Tool Proofs:** Advanced tools don't just say "Fix this." They provide the supporting data (clicks, benchmarks, thresholds) so you can verify the logic. * **No Black Boxes:** The intelligence tools are open-source. You can see exactly how a "cannibalization conflict" score is calculated in our SEO engine. ## Boundary Defenses The MCP server is explicitly built **NOT** to do certain things: * **No Auto-Writing:** It does not generate content for your site. This prevents low-quality "AI slop" from being pushed to your pages. * **No Direct Site Editing:** It cannot change your HTML, CMS, or DNS settings. * **No Credential Leakage:** The server is designed to prevent leaking your service account email or project ID to the model unless explicitly required. ## Your Responsibilities While the server is secure, you are responsible for: 1. **Protecting your machine access.** Your tokens are encrypted with your machine ID, so physical access or remote execution on your specific machine is required to decrypt them. 2. **Reviewing Access.** Regularly check [Google Account Permissions](https://myaccount.google.com/permissions) to see which apps have access to your data. 3. **Prompt Oversight.** Always review the agent's findings before making significant business decisions. # Adding New Tools Source: https://searchconsolemcp.saurabh.app/contributing/adding-tools How to extend the SEO engine. We welcome contributions of new SEO intelligence tools. To maintain the quality of the project, please follow these guidelines. ## Where to add logic 1. **Core Logic:** Add your calculation logic to `src/tools/analytics.ts` or a new file in `src/tools/`. 2. **Tool Registration:** Register the MCP tool in `src/index.ts`. 3. **Schemas:** Use **Zod** to define strict input schemas for your tool. ## Guidelines for Intelligence Tools If you are adding an "Intelligence" tool (one that performs analysis rather than just returning data): * **Be Deterministic:** If your tool uses a threshold (like "min impressions"), make it a user-controllable parameter. * **Return Proof:** Include the raw metrics that led to the conclusion in the output. * **Use Standard Methodologies:** Reference established SEO practices (e.g., Strike Distance is commonly defined as positions 11-20). * **Documentation:** Add a dedicated page for your tool in the `docs/tools/` directory. ## Example Tool Workflow ```mermaid theme={null} sequenceDiagram participant Agent participant Index participant SEOEngine participant GoogleAPI Agent->>Index: Calls your_new_tool(siteUrl) Index->>SEOEngine: Runs deterministic check SEOEngine->>GoogleAPI: Fetches required raw data GoogleAPI-->>SEOEngine: Returns JSON SEOEngine->>SEOEngine: Filters/Calculates/Analyzes SEOEngine-->>Index: Returns specific findings Index-->>Agent: Returns Markdown/JSON summary ``` # Project Philosophy Source: https://searchconsolemcp.saurabh.app/contributing/philosophy The core principles behind search-console-mcp. We aren't just building a software tool; we are building a new way for humans and AI to collaborate on search engine optimization. ## 1. Determinism > Hallucinations We believe that AI agents are at their most powerful when they use deterministic tools. An agent should never "guess" your average position or "estimate" your traffic growth. The MCP server handles the math; the agent handles the strategy. ## 2. Explainability is a Requirement SEO is a high-stakes field. A single wrong recommendation can cost a company thousands of dollars in revenue. Every tool in this MCP server is designed to provide "proof" of its findings—benchmark data, statistical scores, and raw metrics. ## 3. Agents are First-Class Citizens We don't design for human eyes first; we design for agentic "hands." Our tool outputs are structured to be easily parsed by LLMs, using Markdown tables and clear JSON schemas. ## 4. No "AI Slop" This project is strictly for **Analysis and Intelligence**. We do not include tools for automated content generation or bulk "AI optimization." We believe the most valuable use of AI in SEO is identifying *where* to focus, not mass-producing low-quality content. ## 5. Security & Privacy Your SEO data is one of your most valuable assets. This MCP server is designed to run locally and communicate directly with Google and Bing. We will never add telemetry or cloud-processing of your performance data. # Testing Source: https://searchconsolemcp.saurabh.app/contributing/testing Ensuring the integrity of our SEO tools. Reliability is the core of this project. Any new tool or logic must be accompanied by tests that verify its deterministic output. ## Test Suite We use **Vitest** for our unit and integration tests. ### Running Tests To run the unit and integration tests: ```bash theme={null} npm test ``` To run the full suite, including end-to-end tests: ```bash theme={null} npm run test:all ``` ### End-to-End Tests The `tests/e2e/` directory contains true end-to-end tests that spawn the **built server binary** (`dist/index.js`) as a child process and speak the MCP protocol to it with a real client — exactly like Claude or Cursor do: * `stdio.e2e.test.ts` — initialize handshake, `tools/list`, prompts/resources listing, tool calls (`get_started`, unconfigured error paths), schema-validation errors, unknown tools. * `sse.e2e.test.ts` — boots the server in HTTP/SSE mode (`serve --transport=sse`) and checks `/health` plus session rejection. The spawned servers run fully isolated (throwaway `HOME`, no `.env`, no credentials), so they are deterministic and never touch real accounts. ```bash theme={null} npm run test:e2e # builds first, then runs the e2e suite npm run test:all # unit + e2e ``` CI runs both suites on every pull request. ### Writing a Tool Test When testing an SEO tool, focus on verifying the math and the filtering logic. ```typescript theme={null} import { findStrikingDistance } from '../src/tools/seo-insights'; describe('findStrikingDistance', () => { it('should only return keywords in positions 8-15', async () => { // Mock GSC data... const result = await findStrikingDistance(mockSite, { limit: 10 }); result.forEach(item => { expect(item.position).toBeGreaterThanOrEqual(8); expect(item.position).toBeLessThanOrEqual(15); }); }); }); ``` ## Mocking Google Data We prefer using mock data for standard unit tests to avoid hitting API rate limits during CI/CD. Check `tests/mocks.ts` for existing search performance mocks. ## CI/CD Workflow Every pull request triggers our GitHub Actions CI, which: 1. Installs dependencies. 2. Builds the project. 3. Runs the test suite. 4. Generates a coverage report. Please ensure your changes do not decrease the overall project test coverage. # Managing Accounts Source: https://searchconsolemcp.saurabh.app/getting-started/accounts View, remove, and update your connected accounts. ## View Your Accounts See all connected accounts at a glance: ```bash theme={null} npx search-console-mcp accounts list ``` This shows each account's name, engine (Google, Bing, GA4, or AdSense), and which sites it has access to. *** ## Remove an Account No longer need an account? Remove it by name: ```bash theme={null} npx search-console-mcp accounts remove --account=marketing@company.com ``` *** ## Add a Site to an Account By default, a connected account can access **all sites** on that credential. If you want to limit it to specific sites, add a site boundary: ```bash theme={null} npx search-console-mcp accounts add-site --account=marketing@company.com --site=example.com ``` You can also restrict sites during setup — the wizard will show you a list of available sites and let you pick which ones to include. *** ## Remove a Site from an Account To remove a specific site from an account's access list: ```bash theme={null} npx search-console-mcp accounts remove --site=example.com ``` # Authentication Source: https://searchconsolemcp.saurabh.app/getting-started/authentication Authentication for Google Search Console and Bing Webmaster Tools. To use this MCP server, you must authenticate with the Google Search Console API. We recommend the **Secure Desktop Flow**, which uses your local machine's keychain and hardware-bound encryption to store tokens safely. ## 1. OAuth 2.0 Desktop Flow (Recommended) This method allows you to log in with your Google account via a browser, just like any other desktop application. ### Security Features * **System Keychain**: Tokens are stored in your OS's native credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service). * **Hardware-Bound Encryption**: Fallback storage uses AES-256-GCM with a key derived from your unique machine ID. Tokens cannot be decrypted on other devices. * **Multi-Account Support**: Easily switch between multiple Google accounts. ### How to Login Run the following command in your terminal: ```bash theme={null} npx search-console-mcp setup ``` 1. A local secure server will start. 2. Your browser will open to the Google Authorization page. 3. Grant access to your Search Console data. 4. The CLI will automatically fetch your email and securely store your credentials. ### Logout & Management You can manage your sessions directly from the CLI: ```bash theme={null} # Logout of the default account npx search-console-mcp logout # Logout of a specific account by email npx search-console-mcp logout user@gmail.com ``` *** ## 2. Service Account (Advanced / Headless) For server-side environments or automated tasks where interactive login isn't possible, you can use a Google Cloud Service Account. ### Step 1: Create a Service Account 1. Go to the [Google Cloud Console](https://console.cloud.google.com/). 2. Create a new project (or select an existing one). 3. Go to **IAM & Admin** > **Service Accounts**. 4. Click **Create Service Account**. 5. Give it a name (e.g., `seo-agent`) and click **Create and Continue**. 6. Click **Done**. ### Step 2: Generate a JSON Key 1. In the Service Accounts list, click on your new account. 2. Select the **Keys** tab. 3. Click **Add Key** > **Create new key**. 4. Select **JSON** and click **Create**. 5. A JSON file will download to your computer. **Keep this file secure.** ### Step 3: Grant Access in Search Console You must give your Service Account permission to see your data: 1. Open the [Google Search Console](https://search.google.com/search-console). 2. Go to **Settings** > **Users and permissions**. 3. Click **Add User**. 4. Enter the **Service Account Email** (e.g., `seo-agent@your-project.iam.gserviceaccount.com`). 5. Select Permissions (Full or Restricted) and click **Add**. ### Step 4: Configure the Server Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to your key file: ```bash theme={null} export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json" ``` *** ## 3. Bing Webmaster Tools (API Key) To access Bing data, you simply need an API Key. ### Step 1: Get Your API Key 1. Go to [Bing Webmaster Tools Settings](https://www.bing.com/webmasters/settings/api). 2. Log in with your Microsoft account. 3. Click **Generate API Key**. 4. Copy the key. ### Step 2: Configure the Client You can configure the Bing API Key in your MCP client configuration using the `BING_API_KEY` environment variable. **Example for Claude Desktop:** ```json theme={null} { "mcpServers": { "search-console": { "command": "npx", "args": ["-y", "search-console-mcp"], "env": { "BING_API_KEY": "YOUR_BING_API_KEY" } } } } ``` ### Setup Wizard support Alternatively, run `npx search-console-mcp setup` and choose Option 3 to configure your Bing API Key interactively. *** ## 4. Google Analytics 4 (Service Account) GA4 integration currently requires a Service Account for the most reliable connection. ### Step 1: Automated Setup Run the setup wizard with the GA4 flag: ```bash theme={null} npx search-console-mcp setup --engine=ga4 ``` ### Step 2: Granting Property Access Just like Search Console, you must add your Service Account email to your GA4 property: 1. Open [Google Analytics](https://analytics.google.com/). 2. Go to **Admin** > **Property Settings** > **Property Access Management**. 3. Click the blue **+** button > **Add users**. 4. Enter the **Service Account Email**. 5. Select the **Viewer** role (minimum) and click **Add**. *** ## 5. Google AdSense (OAuth) The AdSense Management API supports **user-authorized OAuth 2.0 only** — service accounts are not accepted. ### Step 1: Automated Setup Run the setup wizard with the AdSense flag: ```bash theme={null} npx search-console-mcp setup --engine=adsense ``` ### Step 2: Consent & Account Selection 1. Approve the read-only `adsense.readonly` scope in the browser window. 2. If your Google account has multiple publisher accounts, select the one to connect. 3. Setup runs a live validation query before saving — you'll see **Connection successful!** when done. Enabling AdSense requires this separate consent step; your existing GSC, Bing, and GA4 configuration is never touched until you opt in. ### Headless servers (Docker, CI, VPS) AdSense cannot use service accounts, and config files are machine-encrypted — credentials can't be copied between machines. Instead, authorize once on any machine with a browser and transfer the grant: 1. **On your laptop** (after `setup --engine=adsense`): ```bash theme={null} npx search-console-mcp adsense-export ``` This prints a ready-to-run `adsense-import` command containing the refresh token and publisher ID. 2. **On your server**: ```bash theme={null} npx search-console-mcp adsense-import --token='...' --publisher-id='accounts/pub-...' ``` The token is validated live against Google before being stored, then saved encrypted on the server and refreshed automatically — no browser needed again. If you connect over SSH, you can also authorize directly on the server: when no browser is detected, `setup` prints the authorization URL plus port-forward instructions (`ssh -L 3000:localhost:3000 user@server`) instead of failing. This works for all engines. Full parameter reference: [Google AdSense Tools](/tools/adsense). *** ## 6. PageSpeed Insights (Optional API Key) PageSpeed tools (`pagespeed_analyze`, `pagespeed_core_web_vitals`, `analytics_pagespeed_correlation`) work **without any configuration** using Google's free tier. For heavy usage (batch audits, automated monitoring), you can provide an API key to increase quotas. | Scenario | Daily Limit | Rate Limit | | -------------------- | ------------------ | --------------- | | No API key (default) | \~100 queries/day | \~1 query/sec | | With API key | 25,000 queries/day | \~4 queries/sec | ### Step 1: Create an API Key 1. Go to the [Google Cloud Console — Credentials](https://console.cloud.google.com/apis/credentials). 2. Click **Create Credentials** > **API key**. 3. Copy the generated key. ### Step 2: Enable the API 1. In the same GCP project, go to **APIs & Services** > **Library**. 2. Search for **PageSpeed Insights API**. 3. Click **Enable**. ### Step 3: Configure Set the `PAGESPEED_API_KEY` environment variable in your MCP client or `.env` file: ```bash theme={null} export PAGESPEED_API_KEY="your-api-key-here" ``` This key is optional. Without it, all PageSpeed tools still work — just at lower rate limits. *** ## What's Next? Once you're authenticated, you can manage your accounts and connect additional ones: * [Managing Accounts](/getting-started/accounts) — List, remove, and restrict accounts from the CLI. * [Multi-Account Support](/getting-started/multi-account) — Connect multiple Google and Bing accounts and let the server pick the right one automatically. # First Queries Source: https://searchconsolemcp.saurabh.app/getting-started/first-queries Testing your SEO agent for the first time. Once the server is installed and authenticated, it's time to test it. Open your MCP-compatible client (like Claude Desktop) and start a conversation. ## Step 1: Verify Connection Start by asking the agent what it can see. This verifies that the authentication is working. **User Prompt:** > "List the sites I have access to in Search Console." **Expected Agent Response:** > "I can see the following **Google Search Console** sites: > > 1. [https://example.com](https://example.com) > 2. [https://myblog.org](https://myblog.org) > > I can see the following **Bing Webmaster Tools** sites: > > 1. [https://example.com](https://example.com)" ## Step 2: Get a Basic Performance Summary Now, ask for a high-level overview of a specific site. **User Prompt:** > "Give me a summary of how [https://example.com](https://example.com) performed in the last 28 days on both Google and Bing." **Expected Agent Steps:** 1. Call `compare_periods` for Google. 2. Call `bing_rank_traffic_stats` for Bing. 3. Synthesize the answer. ## Step 3: Run an Intelligence Tool This is where the power of the MCP shines. Instead of asking for data, ask for an analysis. **User Prompt:** > "Can you find any 'quick wins' for [https://example.com](https://example.com)? I'm looking for pages ranking just off the first page." **Expected Agent Steps:** 1. Call `seo_quick_wins` for Google. 2. Call `bing_opportunity_finder` for Bing. ## Step 4: Run a Site Health Check Now try the health check tool to get an instant diagnostic across your properties. **User Prompt:** > "Run a health check on all my sites (Google and Bing) and tell me which ones need attention." The agent will use the `sites_health_check` and `bing_sites_health` tools to check performance trends, sitemap status, and traffic anomalies. ## Step 5: Correlate Search with Behavior (GA4) If you've connected a GA4 property, you can run cross-platform analysis. **User Prompt:** > "Analyze [https://example.com](https://example.com) using the opportunity matrix. Which keywords are ranking well on Google but have poor engagement on-site?" **Expected Agent Steps:** 1. Call `opportunity_matrix`. 2. This will internally fetch GSC rankings and correlate them with GA4 metrics (sessions, engagement rate). ## Step 6: IndexNow (Bing Only) If you have a site verified on Bing, try notifying them of a new URL. **User Prompt:** > "I just published a new post at [https://example.com/new-post](https://example.com/new-post). Notify Bing via IndexNow." The agent will use `bing_index_now` to instantly submit the URL for indexing. ## Tips for Success * **Specify the Site:** Always include the `siteUrl` in your prompt if you have access to multiple sites. * **Be Outcome-Oriented:** Instead of "show me my clicks," say "analyze why my clicks dropped." * **Context is King:** Tell the agent *what* the site is about to get better qualitative insights. # Installation Source: https://searchconsolemcp.saurabh.app/getting-started/installation Get up and running with Google and Bing in less than 2 minutes. We designed `search-console-mcp` to work instantly with your favorite AI editor. No complex configuration required. ## Prerequisites 1. **Node.js 18 or higher** 2. **A verified Google Search Console, Bing Webmaster Tools, or Google Analytics 4 property** ## 🚀 One-Line Setup Run this command in your terminal. The wizard will walk you through connecting your Google and/or Bing accounts. ```bash theme={null} npx search-console-mcp setup ``` The tool will open your browser for secure authentication and then display the exact code snippet to copy-paste into your config. Want to add more accounts later? Just run `setup` again — it supports multiple Google and Bing accounts. *** ## 📦 One-Click MCPB Bundle Installation For **Claude Desktop** or other supported MCP clients, you can skip Node.js installation altogether by downloading the packaged `.mcpb` bundle. 1. Download [`search-console-mcp.mcpb`](https://github.com/saurabhsharma2u/search-console-mcp/releases/latest/download/search-console-mcp.mcpb). 2. Drag and drop the `.mcpb` file directly into **Claude Desktop** (or import it via **Settings → Extensions**). 3. The app will launch the server and present interactive form fields to enter your optional API keys (`GOOGLE_APPLICATION_CREDENTIALS`, `BING_API_KEY`, `PAGESPEED_API_KEY`). *** ## Client Configuration If you prefer to set it up manually, here are the instructions for the most popular clients. ### Claude Desktop Add this to your `claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "search-console": { "command": "npx", "args": ["-y", "search-console-mcp"], "env": { "BING_API_KEY": "your-api-key-here", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account.json", "PAGESPEED_API_KEY": "your-pagespeed-key (optional)" } } } } ``` *That's it! Environment variables are optional and only needed if you are using a Bing API Key, a Google Service Account, or a PageSpeed API Key.* ### Cursor 1. Open **Cursor Settings** (Cmd + ,). 2. Navigate to **Features** > **MCP**. 3. Click **+ Add New MCP Server**. 4. Enter the following: * **Name:** `Search Console` * **Type:** `command` * **Command:** `npx -y search-console-mcp` 5. **Environment Variables (Optional):** Click **Edit** on your new server to add variables if needed: * `BING_API_KEY`: For Bing integration. * `GOOGLE_APPLICATION_CREDENTIALS`: For Google Service Account auth. * `PAGESPEED_API_KEY`: For higher PageSpeed quotas (optional). If you see an error about "command not found," try using the full path to your node executable or `npm` prefix. ### VS Code You can configure the server specifically for your workspace using the standard MCP extension. 1. **Option A: Config File** Create a file named `.vscode/mcp.json` and add: ```json theme={null} { "servers": { "search-console": { "command": "npx", "args": [ "-y", "search-console-mcp" ], "env": { "BING_API_KEY": "your-api-key-here", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account.json", "PAGESPEED_API_KEY": "your-pagespeed-key (optional)" } } } } ``` 2. **Option B: Command Palette** * Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`). * Search for **"MCP: Add Server"**. * Enter the command: `npx -y search-console-mcp`. *** ## Verify Your Setup After installation, confirm your accounts are connected: ```bash theme={null} npx search-console-mcp accounts list ``` This will show all connected Google and Bing accounts and which sites they can access. *** ## What's Next? * [Authentication](/getting-started/authentication) — Detailed auth options (OAuth, Service Account, API Key for Google, Bing, and GA4) * [Managing Accounts](/getting-started/accounts) — List, remove, and restrict accounts across all platforms * [Multi-Account Support](/getting-started/multi-account) — Connect multiple accounts across all platforms * [First Queries](/getting-started/first-queries) — Start asking your AI agent questions # Multi-Account Support Source: https://searchconsolemcp.saurabh.app/getting-started/multi-account Connect multiple Google and Bing accounts and let the server pick the right one automatically. Search Console MCP lets you connect as many Google and Bing accounts as you need. The server automatically picks the right account when your AI agent makes a request. ## Why Multiple Accounts? Common setups include: * A **personal Google account** for your blog * A **company Google account** for your work sites * A **Bing account** for Microsoft search data * A **GA4 Service Account** for behavioral analytics * Separate accounts for **different clients or teams** *** ## Connecting Accounts Run the setup wizard for each account you want to add: ```bash theme={null} npx search-console-mcp setup ``` Choose Google or Bing, complete the login, and give the account a name. Repeat for each account. Running setup again with the same name will update the existing account instead of creating a duplicate. *** ## How the Server Picks the Right Account When your AI agent asks about a specific site (e.g., `example.com`), the server finds the account that has access to that site. If an account is set to "All Sites," it acts as a catch-all. You don't need to specify which account to use — it's handled for you. *** ## Upgrading from an Older Version If you used Search Console MCP before v1.12, your existing credentials will still work. The server automatically detects tokens and API keys from previous versions — no action needed on your part. If you'd like to manage those older accounts (rename them, restrict sites), simply run the setup wizard again and it will bring them into the new system. # Overview Source: https://searchconsolemcp.saurabh.app/getting-started/overview # Search Console MCP **Search Console MCP connects your Google Search Console, Bing Webmaster Tools, Google Analytics 4, and Google AdSense accounts to AI assistants like Claude, so you can ask questions about your site's traffic, rankings, and revenue instead of exporting spreadsheets.** It's an open-source tool built by [Saurabh Sharma](https://github.com/saurabhsharma2u) for site owners, SEO professionals, and developers who want their AI agent to read their site performance data directly. ## What it does You connect your Google and Bing accounts once. After that, your AI agent can pull reports, detect traffic anomalies, find keyword opportunities, and check ad revenue — all through natural-language requests instead of manual dashboard exports. ## Permissions we request | Access | Scope | What it's used for | | --------------------- | --------------------- | ---------------------------------------------------------- | | Google Search Console | `webmasters.readonly` | Read search performance, indexing status, and sitemap data | | Google Analytics 4 | `analytics.readonly` | Read traffic and engagement reports | | Google AdSense | `adsense.readonly` | Read ad revenue and performance reports | | Bing Webmaster Tools | API key (not OAuth) | Read search performance data from Bing | **All access is read-only.** Search Console MCP never modifies, deletes, or shares your data. Nothing is sent to third-party servers — the tool runs locally on your own machine and talks directly to Google's and Microsoft's APIs using your own credentials. ## Who this is for * **Indie hackers & founders** automating weekly SEO reviews * **SEO professionals** investigating traffic drops or ranking changes across many properties * **Developers** building AI agents that need reliable site performance data ## Data & privacy * Credentials are stored locally on your device (OS keychain where available), never on our servers — we don't operate any servers that see your data * You can revoke access at any time from your [Google Account permissions page](https://myaccount.google.com/permissions) * Read our full Privacy Policy and browse the [source code](https://github.com/saurabhsharma2u/search-console-mcp) ## Questions or issues Open an issue on [GitHub](https://github.com/saurabhsharma2u/search-console-mcp/issues) or reach out at \[your support email/contact link]. *** [Get Started →](/getting-started/installation) · [View Documentation →](/docs) · [View on GitHub →](https://github.com/saurabhsharma2u/search-console-mcp) # Claude Desktop Prompts Source: https://searchconsolemcp.saurabh.app/prompts/claude Optimized prompts for analyzing SEO in Claude. Claude is excellent at synthesizing the deterministic data from our MCP server into deep strategic insights. ## The "SEO Audit" Prompt Use this to get a comprehensive view of your site's health. ```markdown theme={null} Run a comprehensive SEO audit for https://example.com. 1. Use the recommendations tool to find high-level opportunities. 2. Check for any keyword cannibalization. 3. Compare the last 28 days to the previous period and summarize the biggest winners and losers. 4. Provide a prioritized list of 3 actions I should take today to increase traffic. ``` ## The "Traffic Drop Detective" Prompt Use this when you notice a decline. ```markdown theme={null} My traffic for https://example.com has dropped recently. 1. Use the time-series tool to find the exact date the drop started. 2. Tell me which pages and queries saw the biggest decrease in clicks. 3. Check the PageSpeed and Indexing status of those pages. 4. Act as a senior SEO consultant and attribute this drop to a specific cause (e.g., technical, algorithm, or seasonality). ``` ## The "Site Health Check" Prompt Use this to get an instant diagnostics overview. ```markdown theme={null} Run a health check across all my verified sites. 1. Use the site health check tool to get the status of each property. 2. For any site with "critical" or "warning" status, investigate the root cause. 3. If there was a traffic drop, check if it correlates with a known Google algorithm update. 4. Provide a prioritized action plan for the most affected sites. ``` ## The "Google vs. Bing" Prompt Use this to find cross-engine opportunities. ```markdown theme={null} Compare my performance on Google and Bing for https://example.com over the last 30 days. 1. Use the compare_engines tool to see which keywords rank well on Google but poorly on Bing. 2. Flag any keywords where I'm overly dependent on Google (85%+ click share). 3. Identify Bing opportunities where I rank in the top 5 on Google but 10+ on Bing. 4. Give me a prioritized list of 3 quick wins to grow my Bing traffic. ``` ## Why these work well * **Chained Tool Use:** These prompts encourage Claude to use multiple tools in sequence before answering. * **Role Prompting:** By asking Claude to "Act as a senior SEO consultant," you improve the quality of the qualitative reasoning it adds to the quantitative data. * **Structured Outputs:** Requesting a "prioritized list" forces the model to weigh different findings against each other. # Cursor Prompts Source: https://searchconsolemcp.saurabh.app/prompts/cursor Using SEO data to drive your development workflow. Cursor allows you to use SEO data directly in your IDE. This is perfect for developers who want to prioritize performance fixes or content updates based on real traffic. ## The "Performance Prioritizer" Prompt Use this in the Chat window to find which files need optimization. ```markdown theme={null} Run a PageSpeed report for my top 5 most visited pages on mobile using the search-console MCP. Cross-reference the results with my local file structure. Which React components or CSS files are most likely responsible for the 'Largest Contentful Paint' (LCP) issues on these pages? ``` ## The "Content Update" Prompt Use this when you want to update metadata or copy. ```markdown theme={null} Find any 'Low CTR Opportunities' for the current site. Compare the queries discovered with the current and <meta description> tags in my codebase for those pages. Suggest improved, keyword-optimized titles that are likely to increase my CTR. ``` ## The "Health Check Dashboard" Prompt Use this to monitor all your sites from your IDE. ```markdown theme={null} Run a health check for https://example.com using the search-console MCP. Show me the overall status, week-over-week performance changes, and any sitemap errors. If there are issues, cross-reference with my local code to see if a recent deploy could have caused them. ``` ## The "Bing Optimization" Prompt Use this to find Bing-specific wins from your IDE. ```markdown theme={null} Compare my site's performance on Google vs. Bing using the compare_engines tool. For any keywords flagged as 'bing_opportunity', check my page's meta tags and structured data. Are there any Bing-specific meta tags (like bingbot directives) missing from my codebase that could improve rankings? ``` ## Why these work well * **Contextual Awareness:** Cursor knows your code. By using the MCP, it also knows your *results*. This bridge allows it to make code suggestions based on search performance. * **Zero-Context Switching:** You don't have to leave your editor to know that your recent deploy slowed down your most important landing page. * **Multi-Engine:** Compare Google and Bing data side by side and fix issues directly in your code. # Generic Agent Prompts Source: https://searchconsolemcp.saurabh.app/prompts/generic-agents Universal prompts for any MCP-compatible agent. If you are building your own agent or using a client not listed here, these prompts follow a "tool-first" structure that works across most LLMs. ## The "Search Discoverability" Check Ensures your content is being found. ```markdown theme={null} 1. List all sitemaps for https://example.com. 2. Check for any sitemap errors. 3. Find any pages in the sitemap that are NOT currently indexed by using the URL inspection tool on a sample of 5 pages. ``` ## The "Portfolio Overview" Useful if you manage multiple properties. ```markdown theme={null} 1. List all sites in my Search Console account. 2. For each site, get the total clicks and impressions for the last 7 days. 3. Which site had the highest percentage growth in non-brand traffic? ``` ## The "Health Check" Prompt Monitor the health of one or all sites. ```markdown theme={null} 1. Run a health check across all my Search Console properties. 2. For each site, report the status (healthy / warning / critical) and any issues found. 3. For sites with critical status, use the drop attribution tool to check for algorithm update correlation. 4. Provide a ranked list of sites that need attention, with specific next steps for each. ``` ## The "Cross-Engine Comparison" Compare Google and Bing performance for any site. ```markdown theme={null} 1. Use the compare_engines tool to compare Google and Bing data for https://example.com over the last 28 days. 2. List the top 10 keywords with the biggest ranking gap between the two engines. 3. Flag any keywords with a 'bing_opportunity' or 'google_dependency_risk' signal. 4. Summarize which engine is underperforming and suggest 3 actions. ``` ## Common Tips for Custom Agents * **Specify Dimension:** When asking for analytics, specify if you want it by `query`, `page`, `country`, or `date`. * **Specify Engine:** Most tools accept an `engine` parameter (`google` or `bing`). Use `compare_engines` to query both at once. * **Limit your scope:** LLMs work best when they process chunks of data. Instead of "Analyze everything," use "Analyze my top 50 pages." * **Ask for reasoning:** Always include "Explain why you reached these conclusions" at the end of your prompt to see the agent's logic. # Magic Prompts Source: https://searchconsolemcp.saurabh.app/prompts/magic-prompts Powerful copy-paste prompts to unlock deep SEO insights with your AI agent. These "Magic Prompts" are designed to be used with AI agents like Claude, ChatGPT, or Cursor. Simply copy and paste them into your chat to trigger sophisticated SEO workflows. ## 🚀 The Quick Win Specialist Use this prompt when you want to find immediate opportunities to increase traffic with minimal effort. ```markdown theme={null} You are an SEO Growth Hacker. Your goal is to find "Striking Distance" keywords—those ranking on page 2 (positions 11-20) that could jump to page 1 with small optimizations. 1. **Analyze Google:** Run `seo_striking_distance` to find keywords with high impressions but ranking just off page 1. 2. **Analyze Bing:** Run `bing_striking_distance` to find similar opportunities on Bing. 3. **Prioritize:** Create a combined table of the top 10 pages. 4. **Audit:** For each page, run `pagespeed_analyze` to see if a slow site is holding it back. 5. **Recommend:** Provide 3 specific actions for each page (e.g., improve title tag, add internal links, fix mobile speed). ``` *** ## 🕵️ The Traffic Drop Detective Use this prompt when you notice a sudden dip in traffic and need to find the "smoking gun." ```markdown theme={null} You are a Senior SEO Forensic Auditor. I've noticed a traffic drop. Help me find out WHY. 1. **Verify:** Run `analytics_anomalies` (Google) and `bing_analytics_detect_anomalies` (Bing) to confirm the exact date the drop started. 2. **Attribute:** Run `analytics_drop_attribution` (Google) and `bing_analytics_drop_attribution` (Bing) to see if it's a specific device, country, or search type. 3. **Cross-Check:** Use `analytics_realtime` (GA4) to see if tracking is still working right now. 4. **Inspect:** For the top 3 affected pages, run `inspection_inspect` to check for indexing errors or manual actions. 5. **Report:** Give me a "Cause & Cure" report: what happened, why it happened, and how to fix it. ``` *** ## 📊 The Cross-Platform Comparator Use this prompt to understand how your brand performs across different ecosystems and identify where you are under-represented. ```markdown theme={null} You are a Multi-Channel Search Strategist. Analyze how this site performs across Google, Bing, and GA4. 1. **Direct Comparison:** Run `compare_engines` to see side-by-side rankings for our top 20 queries. 2. **Brand Strength:** Run `brand_analysis` to compare how often users search for our brand on Google vs. Bing. 3. **Engagement Audit:** Use `analytics_user_behavior` (GA4) to see if users from Google stay longer than users from Bing. 4. **Opportunity:** Identify 5 "Bing-First" opportunities: keywords where we rank well on Bing but are failing on Google. 5. **Strategy:** Recommend a platform-specific strategy for the next 30 days. ``` *** ## ✍️ The Content Gap Explorer Use this prompt to find topics your site *should* be ranking for but isn't, or where your content is decaying. ```markdown theme={null} You are a Content Strategist. Help me find content gaps and decay. 1. **Find Decay:** Run `seo_lost_queries` to identify keywords that used to drive traffic but have disappeared. 2. **Find Low CTR:** Run `seo_low_ctr_opportunities` to find pages that rank well but have boring titles/meta descriptions. 3. **Bing Insights:** Run `bing_seo_recommendations` to see what Bing thinks we are missing. 4. **Consolidate:** Run `seo_cannibalization` to see if we have multiple pages fighting for the same keyword. 5. **Action Plan:** Provide a list of 5 pages to refresh and 3 new topics to cover. ``` # Unified Search Prompts Source: https://searchconsolemcp.saurabh.app/prompts/unified-search Prompts for checking Google & Bing simultaneously. One of the key benefits of this MCP server is the ability to cross-reference data between search engines. If a page drops in Google but not Bing, it's likely an algorithm issue. If it drops in both, it's likely a technical issue. ## The "Master SEO" Prompt Copy and paste this into your agent's system instructions or as a direct prompt. ```markdown theme={null} You are an expert technical SEO analyst with access to both Google Search Console and Bing Webmaster Tools. When I ask you to analyze a site (e.g., "Check the health of https://example.com"), always follow this robust workflow: ### Phase 1: Discovery & Health 1. **List Sites:** Call `list_sites` and `bing_sites_list` to confirm access. 2. **Health Check:** Run `sites_health_check` (Google) and `bing_sites_health` (Bing) in parallel. 3. **Synthesis:** Compare the health status. * If Google is "Critical" and Bing is "Healthy," flag as a potential Google Core Update or penalty. * If both are "Critical," flag as a technical site-wide issue (e.g., server errors, robots.txt). ### Phase 2: Performance Comparison 1. **Traffic Trends:** Compare the last 28 days vs. the previous period using `compare_periods` (Google) and `bing_analytics_compare_periods` (Bing). 2. **Divergence:** Note any major divergence. (e.g., "Google clicks are up 10%, but Bing clicks are down 50%"). ### Phase 3: Actionable Intelligence 1. **Opportunities:** * Run `seo_opportunities` (Google) to find low-hanging fruit. * Run `bing_opportunity_finder` (Bing) to finding ranking gaps. 2. **Recommendation:** Present a unified list of "Top 3 Priorities" based on impact. Prioritize issues that affect *both* engines first. ### Phase 4: Instant Action (Optional) If I provide a new URL, always offer to: 1. Inspect it on Google (`inspect_url`). 2. Submit it to Bing via IndexNow (`bing_index_now`). ``` ## Example Conversation **User:** > "Analyze the drop I saw yesterday on [https://example.com](https://example.com)." **Agent (Guided by Prompt):** > "I'll investigate. First, checking data from both engines to isolate the cause. > ... > **Findings:** > > * **Google:** Traffic dropped 25%. `analytics_drop_attribution` correlates this with the 'August Core Update'. > * **Bing:** Traffic is stable (-2% change), which is within normal variance. > > **Conclusion:** This appears to be a Google-specific algorithmic devaluation, not a technical error on your site. I recommend auditing your content quality rather than checking server logs." # Google AdSense Source: https://searchconsolemcp.saurabh.app/tools/adsense Connect your AdSense revenue data so your AI agent can correlate earnings with search performance. The **Google AdSense** integration closes the loop between traffic and money. Your AI agent can pull earnings, impressions, clicks, CTR, and RPM directly from AdSense and combine them with GSC/Bing/GA4 analysis — no dashboard hopping required. ## Core Capabilities ### Accounts * `adsense_accounts`: List configured publisher accounts, or discover every publisher ID your Google account can access (`mode: "discover"`). ### Reports * `adsense_report`: Earnings & performance reports with dimension breakdowns, metric selection, custom sort order, and row limits. ### Payments & Policy * `adsense_payments_alerts`: Outstanding payment balances plus active account alerts (policy issues, payment holds). *** ## `adsense_report` Parameters | Parameter | Values | Notes | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `dateRange` | `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_7_DAYS`, `LAST_30_DAYS` | Default: `LAST_7_DAYS` | | `startDate` / `endDate` | `YYYY-MM-DD` | Custom range — **overrides `dateRange`** when either is provided | | `dimensions` | `DATE`, `WEEK`, `MONTH`, `DOMAIN_NAME`, `COUNTRY_NAME`, `PLATFORM_TYPE_NAME`, `AD_UNIT_ID`, `AD_UNIT_NAME`, `CUSTOM_CHANNEL_ID`, `CUSTOM_CHANNEL_NAME`, `PRODUCT_NAME`, `PRODUCT_CODE`, `URL_CHANNEL_ID` | Breakdown dimensions | | `metrics` | `ESTIMATED_EARNINGS`, `PAGE_VIEWS`, `IMPRESSIONS`, `CLICKS`, `PAGE_VIEWS_CTR`, `PAGE_VIEWS_RPM`, `IMPRESSIONS_CTR`, `IMPRESSIONS_RPM` | Default: earnings, page views, impressions, clicks, RPM | | `orderBy` | `+METRIC` ascending, `-METRIC` descending | e.g. `-ESTIMATED_EARNINGS` for top-earning first | | `rowLimit` | up to `200` | Default: `100` | | `accountId` | configured profile ID | See note below | <Info> **accountId semantics:** `accountId` refers to the configured profile ID shown by `accounts_manage` (e.g. `adsense_2`) — not a publisher resource name like `accounts/pub-123`. With a single configured account you can omit it entirely. </Info> *** ## Setup & Authentication AdSense uses **user-authorized OAuth 2.0 only** — the AdSense Management API does not support service accounts. 1. **Run Setup**: `npx search-console-mcp setup --engine=adsense` 2. **Consent**: Approve the read-only `adsense.readonly` scope in the browser window. 3. **Account Selection**: If your Google account has multiple publisher accounts, pick one from the list. Setup runs a live validation query before saving. ### Headless servers The AdSense Management API does not support service accounts and config files are machine-encrypted, so use the export/import pair to move an OAuth grant to a server: ```bash theme={null} # On any machine with a browser (after setup): npx search-console-mcp adsense-export # On the headless server: npx search-console-mcp adsense-import --token='...' --publisher-id='accounts/pub-...' ``` `adsense-import` validates the token live, auto-detects the publisher ID when omitted, and stores everything encrypted on the target machine. Over SSH, `setup --engine=adsense` also works directly — it prints the authorization URL plus `ssh -L 3000:localhost:3000` forwarding instructions when no browser is available. <Info> **Existing configurations are untouched.** Enabling AdSense requires a separate consent step; GSC, Bing, and GA4 users never need to re-authenticate until they opt in. </Info> *** ## MCP Resources & Prompts The integration also registers native MCP resources and guided prompts: * `seo://adsense/accounts` — configured publisher accounts * `seo://adsense/payments` — live balances and alerts for every configured account, keyed by account ID * `adsense_earnings_review` — prompt walking your agent through daily trend, top domains, balance, and alerts * `adsense_monetization_audit` — prompt for finding underperforming ad units and geography/platform RPM gaps *** ## Example Prompts > "How much did I earn from AdSense in the last 30 days, and which day was best?" > "Break down my AdSense earnings by domain for this month. Which site drives the most revenue?" > "List any active AdSense policy alerts or pending payments." > "Which ad units have high impressions but low RPM? Use `adsense_monetization_audit`." # Analytics Tools Source: https://searchconsolemcp.saurabh.app/tools/analytics Mastering search performance data across Google, Bing, and GA4. The Analytics tools form the core data engine of Search Console MCP v2.0. They allow you to query raw metrics, perform period-over-period comparisons, detect statistical anomalies, and attribute traffic drops across **Google Search Console, Bing Webmaster Tools, and Google Analytics 4** concurrently. ## Fluent Analytics Tools (v2.0) ### `analytics_query` Unified search & analytics query tool supporting Google, Bing, GA4, or all engines simultaneously in parallel. * **Parameters:** * `siteUrl` (string): Target website URL (e.g. `https://example.com/`). * `engine` (string): `"all"` (default), `"google"`, `"bing"`, or `"ga4"`. * `dimensions` (array): `["query"]`, `["page"]`, `["date"]`, `["country"]`, `["device"]`. * `startDate` / `endDate` (string): Date range `YYYY-MM-DD`. * **Best for:** *"Get top 20 queries across Google and Bing for the last 30 days."* ### `analytics_compare` Analyzes performance deltas, trends, or traffic drop root-cause attributions. * **Modes (`mode`):** * `"period_over_period"`: Compare current period vs. previous period. * `"trends"`: Rolling averages and direction analysis. * `"drop_attribution"`: Correlates traffic drops with Google Algorithm Updates and device loss. * **Best for:** *"Why did my traffic drop last week?"* ### `analytics_anomalies` Statistical anomaly detection that flags unusual traffic spikes or declines outside standard deviation thresholds. * **Parameters:** `siteUrl`, `threshold` (default `2.0` standard deviations). * **Best for:** *"Detect any unexpected traffic anomalies in the last 60 days."* ### `analytics_advanced` High-dimensional Google Analytics 4 reports. * **Metric Types (`metricType`):** `"ecommerce"`, `"realtime"`, `"user_behavior"`, `"audience_segments"`, `"conversion_funnel"`. *** ## ⚡ Parallel Fetching (`engine: "all"`) By passing `engine: "all"` to `analytics_query`, Search Console MCP queries both Google Search Console and Bing Webmaster APIs concurrently in parallel using `Promise.allSettled`, reducing query latency by **50%+**. *** ## 🔄 Backward Compatibility Note All legacy analytics tools (`query_analytics`, `bing_analytics_query`, `analytics_compare_periods`, `analytics_drop_attribution`, `analytics_time_series`, `analytics_page_performance`) are **100% backward compatible** via our fallback router. [Read complete Backward Compatibility Guide →](/concepts/backward-compatibility) # Bing Webmaster Tools Source: https://searchconsolemcp.saurabh.app/tools/bing Analyze your Bing search performance, monitor crawl health, and submit URLs instantly. Search Console MCP includes full support for **Bing Webmaster Tools**. You can analyze Bing traffic, find ranking opportunities, monitor crawl issues, and submit URLs — all through the same AI agent you use for Google. ## What You Can Do ### Search Performance Query your Bing search data the same way you would with Google — clicks, impressions, CTR, and position by keyword, page, country, or device. ### SEO Opportunities Find low-hanging fruit keywords on Bing, get prioritized SEO recommendations, identify **lost queries**, and analyze **brand vs non-brand** performance — all tuned for Bing's ranking behavior. ### Crawl Monitoring See what Bing's crawler is finding on your site — broken pages, redirect chains, and other crawl issues that could hurt your rankings. ### URL Submission & IndexNow Submit URLs directly to Bing's index or use **IndexNow** for instant notifications when your content changes. No waiting for Bing to discover your updates. ### Site Health Run health checks on your Bing properties to catch issues before they affect your traffic. *** ## Example Prompts > "Find my top Bing opportunities — keywords where I have impressions but low rankings. What quick wins can I get?" > "Check my Bing crawl health. Are there any broken pages or redirect issues that Bing is flagging?" > "I just published a new blog post at [https://example.com/new-post](https://example.com/new-post). Submit it to Bing via IndexNow so it gets indexed right away." # Compare Engines Source: https://searchconsolemcp.saurabh.app/tools/compare-engines Compare your site's performance across Google and Bing side by side. The `compare_engines` and `opportunity_matrix` tools let you see how your site performs across **Google, Bing, and GA4** side by side. ## What It Does It pulls data from both Google Search Console and Bing Webmaster Tools, normalizes it, and shows you the differences. For each keyword or page, you'll see: * **Clicks, impressions, CTR, and position** on each engine * **Deltas** — how much the position and CTR differ between engines * **Signals** — automatic alerts that highlight opportunities and risks *** ## Signals The tool automatically flags important patterns: | Signal | What It Means | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `bing_opportunity` | You rank well on Google (top 5) but poorly on Bing (10+). Easy win to optimize for Bing. | | `google_dependency_risk` | Over 85% of your clicks come from Google. You're too dependent on one engine. | | `ctr_mismatch` | Similar rankings on both engines, but very different click-through rates. Your titles or snippets may display differently. | | `ranking_divergence` | A 7+ position gap between Google and Bing for the same keyword. Worth investigating. | *** ## Example Prompts Try these with your AI agent: > "Compare my top keywords on Google vs. Bing for the last 30 days. Which keywords rank better on Bing?" > "Show me keywords where I'm in the top 5 on Google but not ranking well on Bing. These are my Bing opportunities." > "Am I too dependent on Google? Check my click share across both engines." *** ## Parameters | Parameter | Required | Description | | ---------------- | -------- | -------------------------------------------------------------------------- | | `siteUrl` | Yes | Your site URL (e.g., `example.com`) | | `dimension` | No | What to compare: `query`, `page`, `country`, or `device`. Default: `query` | | `startDate` | No | Start date (YYYY-MM-DD). Default: 28 days ago | | `endDate` | No | End date (YYYY-MM-DD). Default: today | | `minImpressions` | No | Only show results with at least this many impressions | | `minClicks` | No | Only show results with at least this many clicks | <Info> You need both a Google and a Bing account connected to use this tool. Run `npx search-console-mcp accounts list` to verify. </Info> # Google Analytics 4 (GA4) Source: https://searchconsolemcp.saurabh.app/tools/ga4 Correlate your search rankings with real user behavior data from GA4. The **Google Analytics 4 (GA4)** integration allows your AI agent to bridge the gap between "visibility" (Google Search Console) and "value" (on-site behavior). By connecting GA4, you can identify which ranking keywords actually drive engaged sessions, conversions, and revenue. ## Core Capabilities Search Console MCP provides a comprehensive suite of GA4 tools: ### Page & Traffic Analysis * `analytics_page_performance`: Detailed page metrics including sessions, engagement rate, and views. * `analytics_traffic_sources`: Analyze sessions segmented by Channel, Source, and Medium. * `analytics_organic_landing_pages`: Focused metrics for organic traffic landing pages. ### Content & Conversion * `analytics_content_performance`: Group performance by Content Grouping. * `analytics_conversion_funnel`: Identify top converting pages and events. * `analytics_ecommerce`: Product-level performance and revenue data. ### Behavioral Insights * `analytics_user_behavior`: Device, Country, and Engagement breakdown. * `analytics_audience_segments`: New vs. Returning users, Age, and OS analysis. * `analytics_realtime`: Live active user data. *** ## Cross-Platform Intelligence (Flagship Tools) The true power of the GA4 integration is found in the **Cross-Platform** tools that combine GSC and GA4 data: ### `opportunity_matrix` The ultimate prioritization tool. It combines GSC impressions and rankings with GA4 engagement and conversion data to find high-value, high-intent opportunities. ### `traffic_health_check` Automatically identifies tracking gaps. If GSC shows 1,000 clicks but GA4 only shows 200 organic sessions, this tool flags a potential tracking or implementation issue. ### `page_analysis` Provides a side-by-side view of a page's search ranking performance vs. its on-site conversion performance. *** ## Setup & Authentication GA4 requires a **Google Cloud Service Account** for authentication. 1. **Run Setup**: `npx search-console-mcp setup --engine=ga4` 2. **Auth Method**: Provide your Service Account JSON key path. 3. **Property Selection**: The setup wizard will list your available GA4 properties and help you select the correct one. <Info> **Important:** You must add the Service Account email as a user with at least "Viewer" permissions in your GA4 Property (Admin > Access Management). </Info> *** ## Example Prompts > "Generate an `opportunity_matrix` for my site. Which keywords have high rankings but low on-site engagement?" > "Is my tracking broken? Compare my GSC clicks to GA4 organic sessions for the last 14 days using `traffic_health_check`." > "Show me my top 5 converting organic landing pages and their current GSC impressions." # Inspection & Performance Source: https://searchconsolemcp.saurabh.app/tools/inspection Monitoring indexing status and page speed across Google, Bing, and PageSpeed Insights. Technical SEO requires verifying crawling, indexing, and Core Web Vitals performance. Inspection & Performance tools enable single or batch URL inspection across Google and Bing alongside full PageSpeed Insights audits. ## Fluent Domain Tools (v2.0) ### `inspection_inspect` Inspects single or batch URLs (up to 10) for Google Search Console and Bing Webmaster Tools. * **Parameters:** * `siteUrl` (string): Target website URL property. * `urls` (array of strings): List of page URLs to inspect (single or batch). * `engine` (string): `"google"` (default), `"bing"`, or `"all"`. * **Best for:** *"Inspect the indexing status of [https://example.com/p1](https://example.com/p1) and [https://example.com/p2](https://example.com/p2)."* ### `pagespeed_analyze` Runs a full PageSpeed Insights analysis returning Lighthouse scores, diagnostics, and Core Web Vitals (LCP, CLS, INP). * **Parameters:** * `url` (string): Page URL to analyze. * `strategy` (string): `"mobile"` (default) or `"desktop"`. * `cwvOnly` (boolean): Optional flag to return Core Web Vitals metrics only. * **Best for:** *"Audit Core Web Vitals for [https://example.com/](https://example.com/) on mobile."* <Tip> Set the `PAGESPEED_API_KEY` environment variable for higher quotas (25,000/day vs \~100/day without a key). See [Authentication](/getting-started/authentication#5-pagespeed-insights-optional-api-key) for setup. </Tip> *** ## 🔄 Backward Compatibility Note All legacy inspection tools (`inspection_inspect`, `inspection_batch`, `bing_url_info`, `pagespeed_analyze`, `pagespeed_core_web_vitals`) are **100% backward compatible** via our fallback router. [Read complete Backward Compatibility Guide →](/concepts/backward-compatibility) # SEO Intelligence Tools Source: https://searchconsolemcp.saurabh.app/tools/seo-intelligence Deterministic analysis and automated audits for strategic organic growth. SEO Intelligence Tools implement server-side SEO math (cannibalization scoring, striking distance filtering, brand regex matching, and opportunity scoring) before passing curated signals into your AI agent's context window. ## Fluent SEO Tools (v2.0) ### `seo_audit` Unified entry point for automated SEO audits across Google and Bing. * **Audit Types (`type`):** * `"quick_wins"`: Queries ranking in positions 8–15 with high impressions. * `"striking_distance"`: Page 2 keywords close to pushing onto Page 1. * `"cannibalization"`: Queries split across multiple competing landing pages. * `"low_hanging_fruit"`: High visibility keywords with low CTR (\< 2%). * `"lost_queries"`: High-value queries that experienced >80% traffic loss. * `"recommendations"`: Automated AI SEO improvement recommendations. * `"brand_vs_nonbrand"`: Brand vs non-brand search visibility breakdown. * **Parameters:** `siteUrl`, `type`, `brandKeywords` (array of brand strings). * **Best for:** *"Run a quick wins and cannibalization audit for [https://example.com/](https://example.com/)."* ### `seo_keywords_research` Keyword statistics and related keyword research via Bing & GSC data. * **Types (`type`):** `"stats"`, `"related"`, `"traffic"`. * **Parameters:** `keywords` (array of strings), `type`. * **Best for:** *"Get search volume and related keywords for 'seo tools'."* ### `schema_validate` Validates JSON-LD structured data and schema markup on target web pages. ### `genai_query_insights` Detects likely generative-AI / AI-Mode / conversational "fanout" queries across Google and Bing performance data. * **Context:** This is **custom heuristic logic** computed locally — no official API is provided by Google or Bing for generative-AI citation data (as of Aug 2026). Google's dedicated Gen AI report is UI-only (its Search Analytics API rejects AI `searchAppearance` values), and Bing's AI Performance report is not yet exposed via its Webmaster API. This tool works around that gap by matching heuristic patterns — prompt verbs (`write`, `generate`, `summarize`, `act as`), follow-ups (`continue`, `show me more`), acknowledgements, question-led and long conversational phrasing — on the regular query-level data both engines already return. * **Parameters:** `siteUrl`, `days` (default 28), `engine` (`google|bing|all`), `includePages` (enrich matched queries with cited/mapped pages), `minImpressions`. * **Caveat (always returned in output):** matches are heuristic and **an undercount** — search engines anonymize rare/conversational queries, and this is not an official report. * **Best for:** *"Which queries look like they're coming from AI Mode or Copilot?"* *** ## 🔄 Backward Compatibility Note All legacy SEO tools (`seo_quick_wins`, `seo_striking_distance`, `seo_cannibalization`, `seo_low_hanging_fruit`, `seo_lost_queries`, `seo_recommendations`, `seo_brand_vs_nonbrand`, `bing_opportunity_finder`) are **100% backward compatible** via our fallback router. [Read complete Backward Compatibility Guide →](/concepts/backward-compatibility) # Site Health Check & Engine Comparison Source: https://searchconsolemcp.saurabh.app/tools/site-health Automated health diagnostics and cross-platform comparisons. The `site_health_check` and `compare_engines` tools provide one-shot cross-platform health checks, technical crawl diagnostics, and side-by-side Google vs Bing performance comparisons. ## Fluent Domain Tools (v2.0) ### `site_health_check` One-shot health check across Google, Bing, and GA4. * **Levels (`level`):** * `"summary"`: Overall health score, WoW click/impression changes, and issues. * `"full"` (default): Full performance deltas, sitemap audit, and anomaly detection. * `"crawl_issues"`: Bing crawl issue diagnostics and HTTP error breakdowns. * **Parameters:** `siteUrl`, `level`. * **Best for:** *"Run a full site health check on [https://example.com/](https://example.com/)."* ### `compare_engines` Compares search performance metrics between Google Search Console and Bing Webmaster Tools side by side. * **Parameters:** `siteUrl`, `startDate`, `endDate`. * **Best for:** *"Compare Google vs Bing performance for the last 30 days."* *** ## 🔄 Backward Compatibility Note All legacy health tools (`sites_health_check`, `bing_sites_health`, `traffic_health_check`, `compare_engines`) are **100% backward compatible** via our fallback router. [Read complete Backward Compatibility Guide →](/concepts/backward-compatibility) # Sites & Sitemaps Tools Source: https://searchconsolemcp.saurabh.app/tools/sites-and-sitemaps Managing verified site properties and sitemap submissions across search engines. Sites & Sitemaps tools allow your AI agent to discover verified properties, configure multi-account profiles, inspect sitemaps, and submit XML feeds to **Google Search Console and Bing Webmaster Tools**. ## Fluent Domain Tools (v2.0) ### `sites_list` Lists verified website properties across search engines concurrently. * **Parameters:** `engine: "all" | "google" | "bing"`. * **Best for:** *"List all verified sites across Google and Bing."* ### `sites_manage` Adds or deletes site properties. * **Parameters:** `action: "add" | "delete"`, `siteUrl`, `engine`. ### `accounts_manage` Manages multi-account profiles and site-to-account assignments. * **Parameters:** `action: "list" | "add_site" | "remove"`, `accountId`, `siteUrl`. ### `sitemaps_list` Lists submitted sitemaps, crawl status, and error counts. * **Parameters:** `siteUrl`, `feedUrl` (optional), `engine: "all" | "google" | "bing"`. ### `sitemaps_submit` Submits a new XML sitemap feed. * **Parameters:** `siteUrl`, `feedUrl`, `engine`. ### `sitemaps_delete` Deletes a sitemap feed. * **Parameters:** `siteUrl`, `feedUrl`, `engine`. *** ## 🔄 Backward Compatibility Note All legacy site and sitemap tools (`sites_list`, `bing_sites_list`, `sites_add`, `sites_delete`, `sitemaps_list`, `bing_sitemaps_list`, `sitemaps_get`, `sitemaps_submit`, `sitemaps_delete`) are **100% backward compatible** via our fallback router. [Read complete Backward Compatibility Guide →](/concepts/backward-compatibility) # Detecting Cannibalization Source: https://searchconsolemcp.saurabh.app/workflows/detect-cannibalization Resolving internal conflicts that hurt your rankings. **User Question:** *"Are any of my pages competing with each other for the same terms?"* Keyword cannibalization occurs when multiple pages on your site target the same query, confusing Google and diluting your ranking power. ## Step 1: Broad Scan The agent scans the entire site for queries where multiple URLs rank in the top 20. **Agent Logic:** * Call `detect_cannibalization` with a lookback of 30 days. * The tool identifies queries where "Page A" and "Page B" both have significant impression share. ## Step 2: Conflict Analysis The agent evaluates the "Conflict Score" provided by the tool. **Agent Logic:** * High Conflict (Score > 0.7): Both pages get similar clicks/impressions. Google is actively swapping them. * Low Conflict: One page dominates, but another "drifts" in occasionally. ## Step 3: Resolution Path The agent analyzes the intent of both pages to suggest a fix. **Agent Logic:** * If Page A is a blog post and Page B is a product page: "Update Page A to link to Page B as the primary authority." * If both are similar blog posts: "Consolidate Page B into Page A and set up a 301 redirect." ## Example Outcome: > "Query: **'mcp vs rest api'** > > * **Conflict Score:** 0.85 > * **Pages:** `/blog/mcp-overview` and `/documentation/protocol-comparison` > * **Finding:** Both pages are ranking at positions 4 and 5. This is likely splitting your click-through rate. > * **Recommendation:** Move the technical comparison from the blog post into the documentation page, and redirect the blog post to the documentation." # Finding Quick Wins Source: https://searchconsolemcp.saurabh.app/workflows/find-quick-wins How to identify and capture low-effort SEO growth. **User Question:** *"I need some easy SEO wins for this project. What should I focus on first?"* This workflow helps an agent identify keywords that are ranking just off the first page but have significant impression volume. ## Step 1: Identify Striking Distance Keywords The agent uses the `seo_quick_wins` tool to find queries ranking in positions 11-20. **Agent Logic:** * Call `seo_quick_wins` with `minImpressions: 500`. * This returns a list of pages that Google already likes but hasn't fully committed to placing on the first page. ## Step 2: Evaluate Content Quality For the top 3 opportunities identified, the agent checks the current indexing and performance status. **Agent Logic:** * Call `get_pagespeed` for each URL to ensure there aren't technical blockers (e.g., poor LCP). * Call `inspect_url` to verify the page is fully indexed and has no mobile usability errors. ## Step 3: Actionable Strategy The agent generates a list of "Quick Wins" with specific instructions. **Example Outcome:** > "I've found 4 'Quick Win' opportunities for [https://example.com](https://example.com). > > 1. **Page:** `/features/ai-search` > * **Query:** 'best ai search tools' > * **Position:** 12 > * **Impressions:** 2,400/mo > * **Action:** This page has high authority but low internal link counts. I suggest adding 3-5 internal links from your high-traffic blog posts to push this to Page 1." ## Step 4: Measuring Success The agent sets a reminder (e.g., in your own task list) to run a `compare_periods` report in 14 days to see if the changes moved the needle. # Investigating a Traffic Drop Source: https://searchconsolemcp.saurabh.app/workflows/investigate-traffic-drop How to root-cause a decline in SEO performance. **User Question:** *"My traffic has dropped 20% this week. Why?"* This workflow shows how an agent uses the MCP to act as a detective and attribute a drop to its root cause. ## Step 1: Confirm the Magnitude The agent starts by verifying the drop and finding the exact start date using `analytics_time_series`. **Agent Logic:** * Call `analytics_time_series` with `days: 30`. * Identify the "inflection point" where clicks started to diverge from the rolling average. ## Step 2: Site-Wide or Specific? Next, the agent determines if the drop is universal or localized to certain segments. **Agent Logic:** * Use `compare_periods` to check: * **By Device:** Is it a mobile-only drop? (Likely PageSpeed or mobile-usability issue). * **By Country:** Is it geographic? (Likely a local Google algorithm update). * **By Search Appearance:** Is it a loss of Rich Snippets? ## Step 3: Page/Query Attribution The agent finds the specific pages or keywords that "lost" the most clicks. **Agent Logic:** * Use `seo_lost_queries` to identify top losers. * Cross-reference with `inspect_url` for those pages to check for manual actions or indexing issues. ## Step 4: Outcome The agent concludes the investigation with an actionable report: > "The 20% drop was concentrated on your **Product pages (mobile only)** starting on Tuesday. URL inspection shows the pages are still indexed, but **PageSpeed** scores dropped from 90 to 45. It appears a recent code update slowed down these pages, leading to a ranking decline." # Weekly SEO Review Source: https://searchconsolemcp.saurabh.app/workflows/weekly-seo-review A professional-grade sitewide audit in 60 seconds. **User Question:** *"What's the high-level health of my site this week? Give me my top priorities."* This is the most common workflow for founders and solo-marketers. It uses the `generate_recommendations` bundle to get a holistic view. ## Step 1: Holistic Analysis The agent runs the "Intelligence Bundle" to scan for opportunities and warnings across all deterministic tools. **Agent Logic:** * Call `generate_recommendations` for the `siteUrl`. * This automatically triggers sub-routines for cannibalization, quick wins, and low-hanging fruit. ## Step 2: Segmented Deep-Dive The agent checks if the "Brand" traffic is stable compared to the "Non-Brand" growth. **Agent Logic:** * Call `analyze_brand_vs_non_brand` using your project's brand regex. * If Brand traffic is dropping, it's a reputation problem. If Non-Brand is dropping, it's an SEO/Algorithm problem. ## Step 3: Performance Check The agent verifies that no recently updated pages have slowed down significantly. **Agent Logic:** * Check the `get_pagespeed` scores for the top 5 traffic-driving pages. ## Step 4: Executive Summary The agent provides a prioritized list of tasks for the upcoming week. **Example Outcome:** > "### Weekly SEO Report: [https://example.com](https://example.com) > > **Overall:** Traffic is up 5%, driven by Non-Brand queries. > > **Top 3 Actions:** > > 1. **Optimize CTR:** Your highest impression query 'best ai tools' ranks #3 but has a CTR of only 1.2%. Update your meta title. > 2. **Push to Page 1:** Found 3 pages at position 12. Adding internal links could double your traffic. > 3. **Fix Speed:** Your home page mobile score dropped to 52/100. Likely due to the new large image assets."