Google Search Console Mcp

gsc-mcp

[](https://pypi.org/project/gsc-mcp-tools/) [](https://python.org) [](https://github.com/FlorianBruniaux/google-search-console-mcp) [](LICENSE)

Google Search Console MCP server with 57 tools covering search analytics, URL inspection, the Google Indexing API, IndexNow, Google Analytics 4, Core Web Vitals (CrUX), sitemap auditing, JSON-LD schema validation and generation, SEO drift monitoring, composite health scoring, on-page content/technical audits, AI crawler visibility, GBP deprecation detection, and PageSpeed Insights integration. Built on Python 3.11+ and FastMCP.

TL;DR: Install with uvx gsc-mcp-tools, point at your GSC service account, and ask Claude things like "which pages on my site are crawled but not indexed? Submit them." The server handles the Google API calls, batching, retries, and quota tracking. All outputs are structured JSON so Claude can reason across results without parsing ambiguity.

No SEO expertise required. You can ask "run a full site audit", "why did my traffic drop last week?", or "which queries are close to page one?" and Claude guides the analysis, explains every metric, and tells you what to fix. See [examples/](examples/) for ready-to-use prompts covering quick audits, full audits, traffic drops, keyword opportunities, and more.

Latest: v1.0.0 (57 tools, Wave C: ai_visibility_audit, gbp_deprecation_lint, pagespeed_audit + schema_validate deprecated-rich-results detection). See the [full changelog](CHANGELOG.md).

What you can do with it

The 57 tools span thirteen families: Properties (list and inspect GSC sites), Analytics (impressions, clicks, CTR, position, anomalies, Discover and News performance), SEO (quick wins, traffic drops, cannibalization, striking-distance queries, parasite SEO risk), Inspection (URL indexing status, batch inspection, issue categorization), Indexing API (single URL submit or true HTTP batch), IndexNow (Bing/Yandex/Seznam/Naver notification), and Sitemaps (list, submit, audit coverage against GSC data). The remaining six families cover GA4 (sessions, engagement, conversions, realtime, multi-step funnels), Cross (GSC+GA4 joined health check and page analysis), CrUX (real-user Core Web Vitals + LCP subpart breakdown), Technical (JSON-LD schema validation with deprecated-rich-results detection, schema generation, AI crawler visibility audit, GBP deprecation lint, PageSpeed Insights), Drift (SEO drift monitoring with baseline snapshots and 17-rule diffs), and Content (on-page quality scoring, hreflang validation, technical meta + robots.txt audit, preload/bfcache audit).

Tools (57)

Show all 57 tools

| Category | Tool | Description | |---|---|---| | Meta | get_capabilities | List all available tools | | Properties | list_properties | List all GSC properties | | Properties | get_site_details | Get details for a specific property | | Analytics | get_search_analytics | Query search performance data | | Analytics | get_performance_overview | Aggregate totals + top queries | | Analytics | compare_search_periods | Compare two consecutive periods | | Analytics | get_search_by_page_query | Performance broken down by page and query | | Analytics | get_advanced_search_analytics | Flexible query with custom dimensions and filters | | Analytics | analytics_anomalies | Z-score anomaly detection on daily clicks | | Analytics | discover_performance | Top pages by impressions in Google Discover | | Analytics | news_performance | Top pages by impressions in Google News | | Analytics | search_type_breakdown | Clicks and impressions split across web, Discover, News, image, video | | Analytics | ai_overviews_impact | Queries with searchAppearance data, graceful 400/403 fallback | | SEO | quick_wins | Pages in positions 4-15 with CTR below benchmark | | SEO | traffic_drops | Queries with declining clicks, with diagnosis | | SEO | check_alerts | Traffic concentration risks and ranking opportunities | | SEO | seo_striking_distance | Queries in positions 8-15, one push away from page 1 | | SEO | seo_cannibalization | Queries split across multiple pages (HHI conflict score) | | SEO | seo_lost_queries | Queries with a click drop >= 80% vs the previous period | | Inspection | inspect_url | URL indexing status via URL Inspection API | | Inspection | batch_url_inspection | Inspect up to 10 URLs at once | | Inspection | check_indexing_issues | Inspect URLs and categorize by issue type | | Indexing | submit_url | Request indexing for a single URL | | Indexing | submit_batch | Request indexing for multiple URLs (true HTTP batch) | | Sitemaps | list_sitemaps | List submitted sitemaps | | Sitemaps | submit_sitemap | Submit a sitemap URL | | Sitemaps | sitemaps_get | Fetch details for a single sitemap | | Sitemaps | sitemaps_delete | Delete a submitted sitemap (with safety check) | | Sitemaps | sitemap_audit | Fetch a sitemap, parse its URLs, cross-reference against 90 days of GSC coverage | | GA4 | ga4_organic_landing_pages | Sessions and engagement for organic landing pages | | GA4 | ga4_traffic_sources | Sessions and conversions by channel, source and medium | | GA4 | ga4_page_performance | 7 metrics per page path, optional CONTAINS filter | | GA4 | ga4_realtime | Active users right now by screen, country and device | | GA4 | ga4_user_behavior | Device, country and user-type breakdowns in one batch call | | GA4 | ga4_conversion_funnel | Converting pages and event counts, optional event filter | | GA4 | ga4_funnel | Multi-step funnel report via GA4 v1alpha RunFunnelReport, conversion rate per step | | Cross | traffic_health_check | GSC clicks vs GA4 organic sessions ratio, flags tracking gaps and filter issues | | Cross | page_analysis | GSC+GA4 join per page with opportunity score, sorted by priority | | Cross | page_health_score | Composite 0-100 score (GSC 30 pts, GA4 25 pts, CrUX 25 pts, schema 20 pts), graceful degradation per component | | Cross | content_brief | Per-page top queries, question queries, and GA4 session data for content planning | | CrUX | crux_page_vitals | Real-user Core Web Vitals (LCP, INP, CLS, FCP, TTFB) for a URL from the Chrome UX Report API | | CrUX | crux_history | Historical Core Web Vitals trend (weekly data points) for a URL | | Technical | schema_validate | Fetch any public URL and validate its JSON-LD schemas; suggests missing schemas by URL pattern | | Technical | schema_generate | Generate a Schema.org JSON-LD block for Reservation, OrderAction, DiscussionForumPosting, or ProfilePage | | Drift | drift_baseline | Capture a baseline snapshot of a page (title, H1-H3, schema, canonical, CWV) stored locally in SQLite | | Drift | drift_compare | Diff a live fetch against the stored baseline and apply 17 rules (8 CRITICAL, 6 WARNING, 3 INFO) | | Drift | drift_history | List previous comparison runs for a URL with triggered findings per run | | Content | content_quality | Fetch a URL and score visible text against E-E-A-T heuristics: filler phrases, information density, repetition, thin content | | Content | hreflang_audit | Fetch a URL and validate its hreflang implementation: x-default, ISO 639-1 codes, region codes, self-ref, protocol consistency | | Content | page_technical_audit | Fetch a URL and audit meta tags (title, description, canonical, robots), viewport, HTML lang, security headers, robots.txt Googlebot access | | Content | preload_audit | Audit Speculation Rules, bfcache eligibility, and LCP preload signals: inline speculationrules blocks, Speculation-Rules header, link preload tags, deprecated prerender, cache-control blockers | | CrUX | crux_lcp_subparts | Decompose LCP into four subparts (TTFB, resource load delay, duration, render delay) with dominant phase identification for targeted CWV remediation | | Indexing | indexnow_submit | Submit URLs to IndexNow (Bing, Yandex, Seznam, Naver) via one POST; SSRF-safe URL validation, skipped-invalid count, ok/partial/error verdict | | SEO | parasite_risk | Scan URL paths for parasite SEO patterns matching Google's 2024-11-19 site-reputation policy: sponsored/affiliate sections, Forbes Advisor, CNN Underscored patterns, affiliate query params | | Technical | ai_visibility_audit | Check robots.txt AI crawler access (GPTBot, Anthropic-ai, PerplexityBot, Google-Extended, CCBot, 9 agents) and llms.txt presence for an origin | | Technical | gbp_deprecation_lint | Scan a page for deprecated Google Business Profile features: .business.site links, Reserve with Google, GBP appointment widgets | | Technical | pagespeed_audit | Run a PageSpeed Insights API v5 audit: Lighthouse performance score, Core Web Vitals, top 3 improvement opportunities (requires GOOGLEAPIKEY) |

Requirements

• Python 3.11+
• A Google Cloud project with the Search Console API, Web Search Indexing API, and Google Analytics Data API enabled
• A Service Account JSON key (recommended) or OAuth Desktop credentials

Installation

uvx gsc-mcp-tools

Or with pip:

pip install gsc-mcp-tools

To run from source:

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 .

Configuration

Full setup guide: [docs/google-setup.md](docs/google-setup.md) covers creating a Google Cloud project, enabling APIs, creating a service account, adding it to GSC with the right permission level, and configuring GA4.

First audit prompts: [docs/starter-prompt.md](docs/starter-prompt.md) contains ready-to-use prompts for a full site audit, a 5-minute health check, single-page inspection, reindexing workflow, and GA4-only analysis.

Quick start (service account)

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
export CRUX_API_KEY=AIza...        # only needed for crux_page_vitals, crux_history
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.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "uvx",
      "args": ["gsc-mcp-tools"],
      "env": {
        "GSC_SERVICE_ACCOUNT_PATH": "/absolute/path/to/service-account.json",
        "GSC_SKIP_OAUTH": "true",
        "GA4_PROPERTY_ID": "123456789",
        "CRUX_API_KEY": "AIza..."
      }
    }
  }
}

Remove GA4_PROPERTY_ID if you are not using GA4 tools. Restart Claude Desktop after saving.

Multi-property support

To query a different GA4 property without changing the config, pass property_id directly to any GA4 or cross tool:

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

CLI usage (gsc-cli)

After installation, gsc-cli is available as a standalone shell command. It wraps all 57 tools from the MCP server and uses the same authentication.

# List all 57 commands
gsc-cli list

# Run any tool (all parameters are flags, no positional args)
gsc-cli get-search-analytics --site https://example.com/ --days 28
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]'

Set GSC_SERVICE_ACCOUNT_PATH for non-interactive use (same as the MCP server). To cache OAuth credentials interactively, run:

gsc-cli auth login --allow-browser

Exit codes: 0 success, 1 Google API error, 2 credential/config error or invalid arguments.

> Quota note: submit-batch and submit-url use the Google Indexing API (200 req/day limit). Each gsc-cli call starts a fresh process, so cross-invocation quota tracking is not implemented. The @with_retry decorator still catches 429s, but the in-process counter resets every call.

Claude agents and skills

The .claude/ directory ships 9 pre-built Claude Code agents and 9 skills. Each agent is wired to a single skill that defines exactly what it does: which tools to call, in what order, and how to format the output.

Agents

Show 9 GSC agents

| Agent | Skill | When to use | |---|---|---| | gsc-seo-reporter | seo-weekly-report | Weekly traffic recap, period-over-period summary | | gsc-traffic-doctor | traffic-drop-diagnosis | Sudden or sustained drop in clicks or impressions | | gsc-content-optimizer | content-opportunities | Pages close to page 1 (positions 4-20) worth a push | | gsc-cannibalization-checker | cannibalization-check | Multiple pages competing for the same query | | gsc-indexing-auditor | indexing-audit | Crawl errors, pages not indexed, coverage gaps | | gsc-sitemap-auditor | sitemap-audit | Sitemap health and declared-vs-indexed coverage | | gsc-schema-auditor | schema-audit | JSON-LD errors blocking rich results | | gsc-page-analyst | page-deep-dive | Full diagnostic for a single URL | | gsc-ai-overviews-analyst | ai-overviews-impact | AI Overview cannibalization on CTR |

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

Skills live in .claude/skills/ and are invokable directly via slash command. They define the exact steps, tool call sequence, and output format. Agents reference them; skills run standalone when you want to drive the workflow yourself without delegating to an agent.

Show 10 SEO skills + 2 dev commands

| Skill | Command | When to use | |---|---|---| | seo-weekly-report | /seo-weekly-report | Weekly traffic recap, period-over-period summary | | traffic-drop-diagnosis | /traffic-drop-diagnosis | Sudden or sustained drop in clicks or impressions | | content-opportunities | /content-opportunities | Pages close to page 1 (positions 4-20) worth a push | | cannibalization-check | /cannibalization-check | Multiple pages competing for the same query | | indexing-audit | /indexing-audit | Crawl errors, pages not indexed, coverage gaps | | sitemap-audit | /sitemap-audit | Sitemap health and declared-vs-indexed coverage | | schema-audit | /schema-audit | JSON-LD errors blocking rich results | | page-deep-dive | /page-deep-dive | Full diagnostic for a single URL | | ai-overviews-impact | /ai-overviews-impact | AI Overview cannibalization on CTR | | python-clean-code | /python-clean-code | Review a module for clean code violations before PR | | add-tool | /add-tool | Step-by-step workflow to add a new MCP tool | | run-tests | /run-tests | Run the pytest suite with automatic failure diagnosis |

For AI assistants

The docs/machine-readable/ directory contains structured architecture docs designed to give any AI agent (Claude, Cursor, Copilot...) an accurate picture of the project without reading the full codebase:

• llms.txt: quick reference covering all 54 tools, module map, security rules, test patterns, and a decision tree for common tasks
• adr-index.yaml: 15 Architecture Decision Records reconstructed from git history
• code-map.yaml: full module/test/dependency map
• constraints.yaml: forbidden patterns (no stdlib XML on external inp

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: FlorianBruniaux
• Source: FlorianBruniaux/google-search-console-mcp
• License: MIT
• Homepage: https://pypi.org/project/gsc-mcp-tools

Install and usage instructions live in the source repository linked above.