Google Search Console MCP Server

A Model Context Protocol (MCP) server that connects AI assistants (ChatGPT, Claude, custom agents) with Google Search Console data. Analyze your SEO data through natural language conversations - ask questions, get insights, and take action without navigating dashboards.

Production Endpoint: https://gsc-mcp-cloud.principal-e85.workers.dev

---

What Is This?

This MCP server acts as a bridge between AI assistants and the Google Search Console API. Instead of manually navigating GSC dashboards, you can ask questions like:

• "What are my top-performing keywords this month?"
• "Find pages that are losing traffic"
• "Check if my new blog post is indexed"
• "What keywords am I ranking 11-20 for that I could push to page 1?"
• "Compare my performance before and after the last algorithm update"

The AI assistant uses this MCP server to fetch real data from your GSC account and provide actionable insights.

---

Who Is This For?

Audience	Use Case
SEO Professionals	Automate reporting, identify optimization opportunities, monitor algorithm impacts
Content Marketers	Find content gaps, track article performance, identify refresh candidates
Web Developers	Check indexing status, debug crawl issues, validate sitemaps
Agency Teams	Manage multiple client properties, generate insights at scale
AI/Automation Enthusiasts	Build custom SEO workflows powered by LLMs

---

Problems It Solves

1. Time-Consuming Manual Analysis - Ask natural language questions instead of clicking through dashboards
2. Missed Optimization Opportunities - AI identifies striking distance keywords and CTR opportunities automatically
3. Reactive SEO - Get proactive alerts about declining pages before they drop off page 1
4. Complex Data Interpretation - AI translates raw data into actionable recommendations
5. Multi-Property Management - Query across all your GSC properties in one conversation
6. Algorithm Impact Analysis - Quickly compare before/after performance around updates

---

Available Tools (26 Total)

OpenAI MCP Integration (2 tools)

Tool	Description
search	Search for relevant documents and data from GSC based on a query
fetch	Retrieve complete document content using a document ID

Property Management (4 tools)

Tool	Description
list_properties	List all Search Console properties with permission levels
add_site	Add a new site to Search Console (URL or domain property)
delete_site	Remove a site from Search Console
get_site_details	Get verification status and ownership details

Search Analytics (5 tools)

Tool	Description
get_search_analytics	Get search data with customizable dimensions (query, page, country, device)
get_performance_overview	Comprehensive performance summary with totals and daily trends
get_advanced_search_analytics	Advanced queries with sorting, filtering, multiple search types (Web, Image, Video, News, Discover)
compare_search_periods	Compare two time periods to identify trends and changes
get_search_by_page_query	Get queries driving traffic to a specific page

URL Inspection (3 tools)

Tool	Description
inspect_url_enhanced	Check indexing status, rich results, crawling details, canonical URLs
batch_url_inspection	Inspect up to 10 URLs at once
check_indexing_issues	Find not-indexed pages, canonical conflicts, robots blocking, fetch errors

Sitemap Management (5 tools)

Tool	Description
get_sitemaps	List all sitemaps with status and URL counts
submit_sitemap	Submit or resubmit a sitemap for processing
list_sitemaps_enhanced	Detailed sitemap list with submission dates, content types, warnings
get_sitemap_details	Deep dive into a specific sitemap's status and errors
delete_sitemap	Remove a sitemap from processing

SEO Analysis Tools (7 tools)

Specialized tools for actionable SEO insights:

Tool	Description	Key Insights
find_high_potential_keywords	Find quick-win keyword opportunities	Keywords ranking 11-40 (striking distance), high impressions with low CTR
check_page_experience	Analyze page experience signals	Mobile usability, crawl status, indexing state
get_coverage_report	Comprehensive indexing analysis	Coverage summary, issue breakdown, action items
analyze_backlinks	Page authority and internal linking*	Top authority pages, hub pages, orphan pages
spot_content_opportunities	Find rising/declining content	Emerging topics, declining pages, refresh candidates
analyze_regional_device_performance	Country and device breakdown	Mobile vs desktop gaps, geo performance
analyze_algorithm_impact	Before/after comparison	Winners, losers, affected queries, recovery recommendations

*Note: External backlink data is NOT available via GSC API. Use Ahrefs/SEMrush for external links.

---

API Limitations

Limitation	Details
Data Lookback	Maximum 540 days (16 months)
Rows Per Query	Maximum 25,000 rows
URL Inspections	2,000 per day per property
No External Backlinks	Only available in GSC Web UI
No Core Web Vitals	Use PageSpeed Insights API or CrUX
Data Delay	GSC data is typically 2-3 days behind

---

Architecture

+-----------------+     +------------------+     +-----------------+
|   AI Assistant  |---->|   MCP Server     |---->|  Google Search  |
|  (ChatGPT, etc) |<----|  (Cloudflare)    |<----|  Console API    |
+-----------------+     +------------------+     +-----------------+
                               |
                               v
                        +--------------+
                        |   KV Store   |
                        | (OAuth tokens)|
                        +--------------+

Stack:

• Runtime: Cloudflare Workers (TypeScript) or local Python (FastMCP)
• Framework: Hono (web), Zod (validation)
• Protocol: MCP over SSE
• Auth: Google OAuth 2.0

---

Deployment Options

Option 1: Cloudflare Workers (Recommended for ChatGPT)

Endpoint: https://gsc-mcp-cloud.principal-e85.workers.dev

Endpoint	Purpose
/health	Health check
/auth	Start Google OAuth flow
/oauth/callback	OAuth callback handler
/mcp-sse	MCP Server-Sent Events endpoint

Setup

cd gsc-mcp-cloud
npm install

# Set OAuth credentials
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET

# Deploy
npm run deploy

# Visit /auth to authenticate with Google

Option 2: Local Python Server (For Claude Desktop)

OAuth Authentication (Recommended)

{
  "mcpServers": {
    "gscServer": {
      "command": "/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json"
      }
    }
  }
}

Service Account Authentication

{
  "mcpServers": {
    "gscServer": {
      "command": "/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/path/to/service_account_credentials.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

---

Example Prompts

Goal	Prompt
Find quick wins	"Find keywords I'm ranking 11-20 for with high impressions"
Content audit	"Show me pages losing traffic over the last 30 days"
Algorithm check	"Compare my performance 2 weeks before and after November 15th"
Indexing audit	"Check if my top 10 blog posts are indexed"
Mobile optimization	"Compare my mobile vs desktop performance by country"
CTR opportunities	"Find queries with high impressions but CTR below 2%"

---

Changelog

v1.3.0 - December 30, 2025, 07:05 UTC

CI/CD & Testing

• Added Vitest testing framework with 53 unit tests
• Test coverage: 80%+ for SEO analysis tools
• Added GitHub Actions workflow for automated testing on push/PR
• Added GitHub Actions workflow for automated Cloudflare Workers deployment
• Deployment triggers on changes to gsc-mcp-cloud/ directory
• Added CI status badges to README

v1.2.1 - December 30, 2025, 05:50 UTC

URL Parsing Fix

• Fixed check_page_experience and get_coverage_report to accept both comma-separated and newline-separated URL lists
• Improved usability for AI assistants passing multiple URLs
• Deployed to production

v1.2.0 - December 30, 2025, 04:30 UTC

SEO Analysis Tools

• Added 7 new specialized SEO analysis tools:
  • find_high_potential_keywords - Striking distance and CTR opportunities
  • check_page_experience - Mobile usability and crawl status
  • get_coverage_report - Comprehensive indexing analysis
  • analyze_backlinks - Page authority based on search visibility
  • spot_content_opportunities - Rising/declining query detection
  • analyze_regional_device_performance - Country and device breakdown
  • analyze_algorithm_impact - Before/after comparison for updates
• Added helper functions: calculatePercentageChange, formatChange, formatDate, getDateRange, getExpectedCTR
• Total tools increased from 19 to 26
• Tested with real GSC data from production properties

v1.1.0 - December 29, 2025, 22:00 UTC

Infrastructure Improvements

• Added FastMCP configuration for Python server
• Implemented Hono error handling middleware with structured JSON responses
• Added cache middleware for health endpoint (5 minute TTL)
• Fixed SSE body consumption error (request cloning fix)
• Improved Zod validation with custom error messages
• Set up Google OAuth 2.0 authentication flow with KV token storage
• Initial deployment to Cloudflare Workers

v1.0.0 - December 29, 2025, 18:00 UTC

Initial Release

• Core MCP server implementation
• 19 tools across 5 categories:
  • 2 OpenAI MCP integration tools
  • 4 Property management tools
  • 5 Search analytics tools
  • 3 URL inspection tools
  • 5 Sitemap management tools
• Python server with FastMCP support
• TypeScript server for Cloudflare Workers

---

Local Development

# TypeScript (Cloudflare Workers)
cd gsc-mcp-cloud
npm install
npm run dev

# Python (FastMCP)
cd mcp-gsc
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python gsc_server.py

---

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Repository: https://github.com/hablapro/mcp-gsc

---

License

MIT License - See LICENSE file for details.