Search Console MCP

Florian BRUNIAUX · AI Founding Engineer @ Méthode Aristote 13 years from developer to CTO / VP Eng · Blog ↗ · Projects ↗

Know what to fix to improve your search rankings, without becoming an SEO expert.

Ask Claude or Codex to analyze your site's latest SEO changes and suggest what to fix first. Search Console MCP gives your assistant the search metrics and page audits it needs to explain traffic drops, find ranking opportunities, and turn the findings into a prioritized action plan.

Search Console MCP is the open-source connection between your data and your AI assistant. The server retrieves metrics and runs analyses; Claude, Codex or another MCP client explains the findings and proposes corrections. A coding assistant with access to your repository can also help implement the fixes you choose.

The diagram covers the 96-tool MCP server. The repository also includes 15 shared Claude/Codex SEO playbooks and a separate opt-in bounded native audit prototype with nine source-review profiles. The post-1.5.0 recap and release-readiness record separates merged source features, published package contents and remaining quality checks.

Website · Documentation · Documentation FR · Sitemap · What’s new · What you get · Use cases · Quick start · Tools · Data limits & safety

What you get

Analyze my site's latest SEO changes. Explain what improved or declined, find opportunities to rank higher, and suggest the fixes I should make first.

Your AI assistant uses the connected tools to produce:

• A diagnosis of recent changes: which pages and queries gained or lost clicks, impressions or positions, with evidence and possible explanations.
• A prioritized list of opportunities: pages close to page one, search results getting impressions but few clicks, and competing pages targeting the same query.
• Concrete suggested fixes: title and description changes, content briefs, internal-link improvements, and technical or indexing issues to investigate.
• A follow-up comparison: rerun the analysis after making changes to see how clicks, impressions and positions evolved.

For example, if a page gets impressions but few clicks, the assistant can inspect its title and description and suggest a rewrite. If a page is close to page one, it can check its content and internal links before recommending changes. These are example workflows, not measured results for your site.

Initial account setup and review of suggested changes are still required. Recurring checks need a scheduler or automation in your client; the server does not run them on its own. Ranking improvements must be measured after the changes and are not guaranteed.

A real audit

See a real analysis of my Claude Code Ultimate Guide site, run on 2026-10-07 with 14 live MCP calls. It measured 459 clicks and 55,921 impressions over 28 days, investigated three pages and proposed actions tied to the observed data. The request/response trace shows the parameters, timestamps and selected results. These are analysis findings; no site correction or ranking gain has been measured from this run.

What it covers

Choose your starting point

New to SEO? Start with a site assessment: understand what to analyze and why, get three first actions, and learn which metrics to follow. You can begin with public pages, then connect Google Search Console for search performance data. GA4 and Bing are optional.

Choose a workflow to get a prompt to copy, the data it needs and an illustrative result:

• Start with SEO: assess your site, get three priorities and a measurement plan, with explanations in plain language.
• Understand a traffic drop: compare periods with Google Search Console; optional GA4 adds visitor behavior.
• Find ranking opportunities: use configured Google or Bing search metrics and inspect the relevant pages.
• Check page visibility: audit public pages and use Google Search Console for indexing status; Bing can add crawl signals.

Replace the example site in the prompt with your own. Every copied prompt explicitly asks the assistant to use Search Console MCP, verify its tools and guide installation or Google setup if needed. It includes the installation guide, Google setup guide and the matching GitHub example. The prompts request analysis and recommendations without applying site changes.

Quick start

Start here

Requirements

• Python 3.11+
• For Google tools: a Google Cloud project with the Search Console API, Web Search Indexing API and Google Analytics Data API enabled, plus a Service Account JSON key or OAuth Desktop credentials
• For Bing tools: a Bing Webmaster Tools account, at least one verified site and a Bing Webmaster API key

Published package

Use the published package for the complete 96-tool registry, including Bing:

uvx gsc-mcp-tools

For a persistent MCP client, install the latest stable package once and configure the absolute executable path. This avoids keeping an extra uvx launcher process beside every running server:

uv tool install gsc-mcp-tools
command -v gsc-mcp-tools
gsc-cli list

Upgrade that installation when a new release is available:

uv tool upgrade gsc-mcp-tools

To reproduce this release exactly, use uv tool install --force gsc-mcp-tools==1.6.0. A version-pinned installation remains pinned; install a newer explicit version or reinstall without ==... before using uv tool upgrade.

Release 1.2.0 was built and published by GitHub Actions through PyPI Trusted Publishing. The workflow checks that the tag matches pyproject.toml, runs the full test suite, validates and smoke-tests the built wheel, then publishes that same artifact with a short-lived OIDC credential. See the GitHub release and PyPI files.

pip install gsc-mcp-tools

Configure the providers you use

Installation guide: docs/installation.md covers persistent and one-time installs, upgrades, Codex project scoping, Claude Desktop, provider variants and verification.

Provider setup: docs/google-setup.md covers Google credentials and GA4. docs/bing-setup.md covers the Bing Webmaster API key, verified sites and the separate IndexNow key.

First audit prompts: docs/starter-prompt.md contains ready-to-use prompts for Google, Bing, cross-engine comparison, single-page inspection, eligible Indexing API submissions and GA4 analysis.

Use only the variables required by the provider families you enable:

export GSC_SERVICE_ACCOUNT_PATH=/absolute/path/to/service-account.json
export GSC_SKIP_OAUTH=true
export GA4_PROPERTY_ID=123456789   # only needed for GA4 tools
# Load CRUX_API_KEY from your secret store for CrUX tools.
# Load BING_WEBMASTER_API_KEY from your secret store for Bing tools.
gsc-mcp

CRUX_API_KEY is a Google API key (not a service account) with the Chrome UX Report API enabled in your GCP Console. It is separate from GSC auth and only required for CrUX tools.

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "/absolute/path/to/gsc-mcp-tools",
      "env": {
        "GSC_SERVICE_ACCOUNT_PATH": "/absolute/path/to/service-account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

uv tool install gsc-mcp-tools
command -v gsc-mcp-tools

[mcp_servers.gsc-mcp]
command = "/absolute/path/to/gsc-mcp-tools"
startup_timeout_sec = 60

[mcp_servers.gsc-mcp.env]
GSC_SERVICE_ACCOUNT_PATH = "/absolute/path/to/service-account.json"
GSC_SKIP_OAUTH = "true"

Select MCP tool families (since 1.3.1)

Since version 1.3.1, set GSC_MCP_TOOL_FAMILIES=analytics,seo,sitemaps,links in the MCP server environment to expose these families plus core. The default exposes all 96 tools in version 1.6.0. Restart the server or client after changing the selection; gsc-cli list keeps the full catalogue. Selection does not grant provider access or write permission. See the tool-family configuration for all family names and startup validation. Version 1.3.0 predates this setting.

Bing Webmaster API key

1. Sign in to Bing Webmaster Tools and verify every site you want the account to access.
2. Open the API access settings and generate an API key.
3. Store the key in your secret manager or local environment as BING_WEBMASTER_API_KEY. Never pass it as a tool argument or commit it to a file.
4. Call each Bing tool with its site argument, for example https://example.com/. One user-level key can access every verified site visible to that account.

The Bing Webmaster API key and the IndexNow key have different scopes:

• Bing Webmaster API reads private account data and manages verified sites. The server reads its user-level key from BING_WEBMASTER_API_KEY.
• IndexNow notifies participating engines about changed URLs. Its key must be verifiable on each target host or subdomain, and indexnow_submit currently receives that key as an explicit argument.
• The Bing Webmaster Tools web interface exposes features that the public API does not. Full URL Inspection and AI Performance are not available through the public API used here.

Do not reuse the Bing Webmaster API key as an IndexNow key.

ga4_traffic_sources(property_id="987654321")
traffic_health_check(site="sc-domain:example.com", property_id="987654321")

Troubleshooting

The data behind the recommendations

Google Search Console and Bing Webmaster Tools show how people find your pages in search. Optional GA4 data adds what those visitors do on your site; CrUX and public-page audits help identify performance, content and technical issues. Your assistant can use these sources together to decide which pages need attention.

Version 1.6.0 exposes 96 FastMCP tools, including local log analysis, four crawl snapshot commands, inventory differences and an indexing evidence matrix. The server handles authentication, API calls, validation, retries and structured JSON output. Use a starter prompt to run your first analysis.

Why private search data needs MCP

Public web search cannot answer questions tied to private Search Console, Bing Webmaster Tools or GA4 properties. Search Console MCP lets an assistant analyse those measured values while preserving provider boundaries and uncertainty.

How it works

flowchart TD
    C[Claude, Codex<br/>or another MCP client] --> S[FastMCP server]
    S --> R[Shared source registry<br/>96 tools]
    R --> A[Read and analysis tools]
    R --> W[Guarded write tools]
    A --> G[Google APIs<br/>GSC, GA4, CrUX]
    A --> B[Bing Webmaster API]
    A --> P[Public pages<br/>robots, sitemaps, HTML]
    A --> L[(Local drift baselines)]
    W --> V[Validate target, scope<br/>and explicit confirmation]
    V --> M[Google indexing and sitemaps<br/>Bing submissions and IndexNow]
    G --> O[Structured JSON<br/>facts, derived values and _meta]
    B --> O
    P --> O
    L --> O
    M --> O
    O --> C

Google and Bing share clicks, impressions and derived CTR where those fields exist. Provider-specific values remain separate, and cross-engine deltas appear only when both observed windows are exact and equal.

Evidence and safety

Every tool returns structured JSON. The _meta block records diagnostics such as the provider and observed window where the tool can establish them. Search Console MCP does not turn an unavailable field into a negative result or merge Google and Bing ranking semantics into one number.

GA4 reports identify the effective property in _meta.sources.ga4.property, including when GA4_PROPERTY_ID supplies the default. Combined reports also retain the requested GSC property in _meta.sources.gsc.site. _meta.params preserves the original inputs, so an omitted property_id can remain null there while the resolved source is known. Missing child provenance remains null; the server does not infer a GA4-to-GSC site mapping. See the source identity contract.

Remote writes require the agent to identify the exact target and volume, read current state where available, and obtain explicit confirmation before calling the tool. The returned API status is reported without extrapolating crawl, indexation or ranking effects.

Search engine coverage

Tools (96)

Version 1.5.0 includes the bounded local crawl-log audit. Its validation record distinguishes declared bots and current registry membership from historical identity.

The versioned crawl inventory contract adds optional site-owned local storage, bounded detail pages, exact-URL reconciliation and explicit cleanup. Imported metadata and scores are not independently verified provider evidence.

Release gsc-mcp-tools==1.3.0 includes ga4_ai_referrals, editorial_audit, search_change_breakdown and link_targets_audit, field-level evidence methods, content-trust observations and comparison/challenge fixes. Version 1.3.1 retains 85 tools and adds optional MCP discovery selection, CLI JSON string lists, and the SEO/Bing feedback fixes described in the changelog. Version 1.4.0 has 89 tools, adding declared-change follow-up, draft/rewrite checks, weekday-reference and caller-supplied crawl previews described in bounded audit workflows and editorial workflows. Version 1.5.0 adds seven local evidence tools, richer traffic references and an opt-in extraction profile. Version 1.6.0 retains 96 tools, fixes missing comparison/indexing values and packages experimental audit/native APIs; runner scripts and workspace skills require the repository checkout. See the evidence and safety guide for availability, source matching and method limits.

CLI usage

After installation, gsc-cli is available as a standalone shell command. It derives its commands from the same registry as the MCP server. Version 1.6.0 retains the 96 commands from 1.5.0. Version 1.4.0 has 89 commands, up from 85 in releases 1.3.0 and 1.3.1, adding seo_change_impact, rewrite_fidelity_check, search_weekday_reference and crawl_import_preview. Draft inputs extend editorial_audit without adding a command. Version 1.2.0 has 81 commands. MCP family selection does not restrict CLI commands.

# List the commands in the installed build
gsc-cli list

# Run Google or Bing tools with flags
gsc-cli get-search-analytics --site https://example.com/ --days 28
gsc-cli bing-query-stats --site https://example.com/ --days 28 --limit 100

Bing from the CLI

# Load BING_WEBMASTER_API_KEY from your local secret store before this command.
gsc-cli bing-sites-list
gsc-cli bing-query-stats --site https://example.com/ --days 28 --limit 100
gsc-cli compare-search-engines \
  --google-site sc-domain:example.com \
  --bing-site https://example.com/ \
  --days 28 \
  --dimension query

BING_WEBMASTER_API_KEY is process configuration. It never appears in the CLI flags, tool parameters, result metadata or sanitized Bing errors.

# Run another registered tool
gsc-cli get-performance-overview --site https://example.com/

# Multi-value flags for list parameters
gsc-cli batch-url-inspection \
  --urls https://example.com/page-1/ \
  --urls https://example.com/page-2/ \
  --site https://example.com/

# GA4 funnel with a JSON steps array
gsc-cli ga4-funnel \
  --steps '[{"name":"Visit","event":"page_view"},{"name":"Convert","event":"purchase"}]' \
  --start-date 28daysAgo \
  --end-date today

# Keep the _meta diagnostic block in output
gsc-cli list-properties --meta

# Pipe to jq
gsc-cli get-search-analytics --site https://example.com/ | jq '.rows[:5]'

gsc-cli batch-url-inspection --site https://example.com/ \
  --urls '["https://example.com/page-1/","https://example.com/page-2/"]'

gsc-cli auth login --allow-browser

Agents and shared SEO skills

The repository ships 13 Claude Code agents, 15 shared SEO skills, one Claude development skill and 2 development commands. The nine SEO workflow agents below each reference a focused skill. A read-only evidence reviewer keeps its findings beside the unapproved draft; three additional specialist agents cover Python implementation, pytest and security review. The controlled workflow pilot records that interactive workflow's bounded checks.

The optional bounded native source workflow uses experimental APIs packaged in 1.6.0 and a checkout runner with nine narrower source-review profiles, immutable acquired observations and durable provider, tool and native-attempt ceilings. Both installed native CLI hosts completed an offline source case; this does not establish authenticated provider acquisition, full interactive playbooks or expert report quality. Current output-limit validation bounds each stdout/stderr stream and regular-file writes to at most 2,000,000 bytes on Linux/macOS, preserves lower inherited file limits and cleans up ordinary process-group descendants. The file ceiling can affect host state; it is not an aggregate disk quota or host memory limit. Version 1.6.0 packages the Python APIs; runner scripts and shared workspace skills still require the repository checkout. No new console command is installed.

The live GSC pilot record describes authenticated acquisition, private storage, explicit windows and identical source projections reviewed by Claude/Codex. This source-only pilot does not validate interactive playbooks or human quality. A Google-only configuration does not require a Bing site.

The initial native client playbook trials record explicit skill loading and MCP replay calls in both clients. Eleven of twelve retained controlled cases passed after targeted instruction retests; the Claude missing-traffic case still overstated an explanation. The separate C1 follow-up adds an insufficient-evidence branch and eight retained cases passing the frozen C1 criteria, including a positive arithmetic control. These verdicts do not establish whole-report accuracy, automatic routing, new provider acquisition or human SEO quality.

Agents

To use an agent from Claude Code, ask naturally ("why did traffic drop?") or invoke it by name. Each agent loads its skill at runtime and returns a structured answer, not a narration of what it did.

Skills

SEO skills have one canonical source in .agents/skills/, discovered by Codex and projected into .claude/skills/ for Claude. Each contains supported calls, evidence limits and shared FR/EN routing cases. Use them directly or through the Claude agents. Shared-playbook validation records discovery and routing checks; the separate native source runner does not execute these interactive playbooks or establish human SEO accuracy.

Documentation

Development

The classifier evaluation guide and human intake worksheet specify independent labels, family-disjoint splits and targets frozen before tuning. Equal declared annotator/reviewer identifiers are rejected; distinct strings do not authenticate humans. The extraction benchmark compares hash-checked local HTML using labeled inclusion/omission snippets. Its release quality remains UNKNOWN, synthetic results are ineligible for adoption and downstream warnings are not_measured. See the remaining action plan for task-specific inputs.

Source checkout for development

git clone https://github.com/FlorianBruniaux/google-search-console-mcp
cd google-search-console-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
gsc-cli list

The final command reads the shared registry and lists the 96 commands available in this checkout. Use this installation when developing or testing unreleased changes; the native audit and evaluation scripts add no public MCP tool or CLI command.

For client executable paths and the distinction between repository skills, Claude Desktop and native source-review profiles, follow the source workflow installation instructions. The Python APIs are packaged in 1.6.0; runner scripts and workspace skills require the checkout. See the 1.6.0 release validation.

pip install -e ".[dev]"
pytest tests/ -v

Project origins

Credits

This project took inspiration from claude-seo (MIT, agricidaniel). Four components were adapted:

• SSRF protection (src/gsc_mcp/url_safety.py): the URL safety module with DNS-rebinding mitigation, IPv4 obfuscation normalization, and multi-cloud metadata endpoint blocklist, ported from requests to httpx.
• JSON-LD generators (schema_generate tool): the four high-leverage schema types (Reservation, OrderAction, DiscussionForumPosting, ProfilePage) adapted from scripts/schema_generate.py.
• Schema templates (src/gsc_mcp/data/schema_templates.json): 11 JSON-LD placeholder templates (VideoObject, ProductGroup, ItemList, Certification, etc.) from schema/templates.json.
• SEO drift monitoring (src/gsc_mcp/tools/drift.py): the 17-rule diff methodology from scripts/drift_baseline.py and scripts/drift_compare.py, credited to Dan Colta in the original CONTRIBUTORS.md.

Assets with incompatible licenses (CC BY-SA 4.0, CC BY 4.0) were excluded. See NOTICE for full attribution.

Explore the ecosystem

These projects extend the workflow without duplicating this tool:

• Research with yt-insights: connect corpus building to post-publication performance measurement.
• Learn with Claude Code Ultimate Guide: frame MCP choice, permissions, and research workflows.

Browse the complete open-source galaxy

License

MIT