mcpengine/servers/google-console/README.md

Google Search Console MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Search Console, providing AI assistants with powerful SEO insights and website performance data. This server delivers 26 tools for search analytics, URL inspection, sitemap management, and intelligent SEO recommendations.

Features

• Search Analytics: Query search performance data with flexible dimensions (query, page, country, device)
• Comparative Analysis: Compare performance across time periods, identify trends and anomalies
• Top Movers Detection: Automatically identify queries with significant ranking changes
• Device Analysis: Compare mobile vs desktop performance metrics
• Geographic Insights: Analyze search traffic by country and region
• URL Inspection: Deep-dive into indexing status, crawl details, and page experience metrics
• Batch URL Inspection: Inspect multiple URLs simultaneously for indexing issues
• Indexing API: Request indexing or removal for specific URLs
• Sitemap Management: Submit, update, and monitor sitemap processing status
• Property Management: List and verify Search Console properties
• SEO Intelligence: Detect quick wins, keyword cannibalization, and content decay
• Query Clustering: Group related search queries for content strategy insights
• Discovery Tools: Interactive tool discovery and capability exploration

Installation

npm install && npm run build

Environment Variables

Google Search Console uses OAuth 2.0 authentication. You can provide credentials via environment variables or a JSON file:

Variable	Required	Description	Example
GSC_OAUTH_CLIENT_ID	Yes*	OAuth 2.0 Client ID	123456789-abc.apps.googleusercontent.com
GSC_OAUTH_CLIENT_SECRET	Yes*	OAuth 2.0 Client Secret	GOCSPX-aBcDeFgHiJkLmNoPqRsTuV
GSC_OAUTH_REDIRECT_URI	No	OAuth redirect URI (default: http://localhost:3000/oauth2callback)	http://localhost:3000/oauth2callback
GSC_OAUTH_CLIENT_FILE	Yes*	Path to OAuth client JSON file (alternative to individual vars)	/path/to/client_secret.json

* Either provide GSC_OAUTH_CLIENT_ID + GSC_OAUTH_CLIENT_SECRET, OR provide GSC_OAUTH_CLIENT_FILE

Getting Your Access Token

Step 1: Create OAuth 2.0 Credentials

1. Go to Google Cloud Console: Visit console.cloud.google.com
2. Create or Select Project:
   • Click the project dropdown at the top
   • Click New Project or select an existing one
3. Enable APIs:
   • Navigate to APIs & Services → Library
   • Search for and enable:
     • Google Search Console API
     • Web Search Indexing API (optional, for indexing features)
4. Configure OAuth Consent Screen:
   • Go to APIs & Services → OAuth consent screen
   • Select External (or Internal if using Google Workspace)
   • Fill in app name (e.g., "MCP Search Console Integration")
   • Add your email as developer contact
   • Add scopes (see Required API Scopes below)
   • Add your email as a test user
   • Save and continue
5. Create OAuth Client ID:
   • Go to APIs & Services → Credentials
   • Click + Create Credentials → OAuth client ID
   • Application type: Desktop app (recommended) or Web application
   • Name: "MCP Server"
   • For Web application, add authorized redirect URI: http://localhost:3000/oauth2callback
   • Click Create
6. Download Credentials:
   • Click the download button (⬇️) next to your newly created OAuth client
   • Save the JSON file as client_secret.json

Step 2: Configure Environment

Choose one of these methods:

Method A: Use JSON file (recommended)

export GSC_OAUTH_CLIENT_FILE="/path/to/client_secret.json"

Method B: Use individual environment variables

export GSC_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GSC_OAUTH_CLIENT_SECRET="GOCSPX-your-secret"
export GSC_OAUTH_REDIRECT_URI="http://localhost:3000/oauth2callback"

Step 3: First-Time Authentication

When you first run the server, it will:

1. Open your browser to Google's OAuth consent page
2. Ask you to grant permissions
3. Redirect to localhost and exchange the code for tokens
4. Save tokens to ~/.gsc-mcp/oauth-token.json

Subsequent runs will use the saved refresh token automatically.

Required API Scopes

The server requests these OAuth 2.0 scopes:

• https://www.googleapis.com/auth/webmasters - Full access to Search Console data
• https://www.googleapis.com/auth/webmasters.readonly - Read-only access (fallback)
• https://www.googleapis.com/auth/indexing - Submit URLs for indexing

Permissions Required:

• Read search performance data
• Inspect URL indexing status
• Submit and manage sitemaps
• Request indexing for URLs
• Verify site ownership
• Access all properties you own or have been granted access to

Note: You must be verified as the owner or have delegated access to a Search Console property to query its data.

Usage

stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "google-console": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/google-console/dist/index.js"
      ],
      "env": {
        "GSC_OAUTH_CLIENT_FILE": "/path/to/client_secret.json"
      }
    }
  }
}

HTTP Mode

The server can also run as an HTTP endpoint:

export GSC_OAUTH_CLIENT_FILE="/path/to/client_secret.json"
npm start -- --http --port 3000

Then configure your MCP client to connect to http://localhost:3000.

Coverage Manifest

Total API endpoints: ~35 (Google Search Console API + Web Search Indexing API)
Tools implemented: 26
Intentionally skipped: ~5 (admin notifications, AMP reports, mobile usability legacy endpoints)
Not yet covered: ~4 (Core Web Vitals detailed reports, manual actions, security issues)
Coverage: 26/35 = 74%

Coverage Notes:

• ✅ Complete: Search Analytics (5 tools), Discovery & Property Management (3 tools), URL Inspection (3 tools), Indexing API (1 tool), Sitemaps (3 tools), SEO Intelligence (4 tools), Advanced Analytics (7 tools)
• ⏭️ Skipped: AMP-specific reports (deprecated), mobile usability (migrated to Page Experience), admin email notifications
• 🚧 Planned: Core Web Vitals field data export, manual action details, security issue alerts, rich results testing

Example Use Cases

• "Show me search analytics for my site in the last 28 days"
• "Which queries had the biggest ranking improvements this month?"
• "Compare mobile vs desktop click-through rates"
• "Inspect the indexing status of https://example.com/new-page"
• "Detect quick SEO wins for pages with high impressions but low CTR"
• "Find keyword cannibalization issues across my site"
• "Request indexing for my new blog post"
• "Get top pages by country breakdown"
• "Identify content that's decaying in search performance"
• "Submit a new sitemap to Search Console"

Architecture

The server uses OAuth 2.0 with token persistence:

• Auth: OAuth 2.0 with interactive browser flow on first run
• Token Storage: Refresh tokens saved to ~/.gsc-mcp/oauth-token.json
• Client: google-auth-library with automatic token refresh
• APIs: Search Console API v1, Web Search Indexing API v3
• Tools: 6 tool modules with 26 total tools
• Rate Limits: Google API quotas (600 queries/minute, 2000/day for Search Console)

Links

• Google Search Console
• Search Console API Documentation
• Web Search Indexing API
• OAuth 2.0 Setup Guide
• API Quotas & Limits
• Search Console Help