Google Search Console MCP Server

# Google Search Console MCP Server [](https://github.com/hablapro/mcp-gsc/actions/workflows/test.yml) [](https://github.com/hablapro/mcp-gsc/actions/workflows/deploy.yml) 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 ```bash 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) ```json { "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 ```json { "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 ```bash # 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](https://github.com/hablapro/mcp-gsc) --- ## License MIT License - See [LICENSE](LICENSE) file for details.