Google Search Console Mcp Server

GSC-MCP-Server

Google Search Console MCP Server — Connect Google Search Console to Claude, Cursor, and other MCP clients.

Features

• 🔍 Search Analytics — Query clicks, impressions, CTR, and position data
• 📊 SEO Opportunities — Find low-CTR keywords, detect cannibalization issues
• 📈 Reports — Weekly summaries, period comparisons
• 🗺️ Sitemaps — List, submit, and manage sitemaps
• 🔎 URL Inspection — Check indexing status (requires full scope)
• 💾 Caching — SQLite cache for faster repeated queries
• 🔐 Secure — OAuth tokens stored in OS keychain

Quick Start

# Install globally
npm install -g @appsyogi/gsc-mcp-server

# Set up OAuth credentials
gsc-mcp init

# Verify setup
gsc-mcp doctor

# Start the server (for MCP clients)
gsc-mcp run

Prerequisites

1. Create Google Cloud OAuth Credentials

You need to create your own OAuth credentials in Google Cloud Console:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Search Console API:
   • Go to "APIs & Services" → "Library"
   • Search for "Google Search Console API"
   • Click "Enable"
4. Create OAuth credentials:
   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "OAuth client ID"
   • Choose "Desktop application"
   • Name it (e.g., "GSC-MCP")
   • Click "Create"
5. Copy the Client ID and Client Secret
6. Add test users (required while app is in testing mode):
   • Go to "APIs & Services" → "OAuth consent screen"
   • Scroll to "Test users" section
   • Click "Add users"
   • Add the Google account email(s) you'll use to authenticate
   • Click "Save"

Note: While your app's publishing status is "Testing", only test users can authenticate. You can add up to 100 test users.

2. Configure GSC-MCP

Run the init command and enter your credentials:

gsc-mcp init

This will:

• Prompt for your Client ID and Client Secret
• Open a browser for Google authentication
• Store your refresh token securely in the OS keychain

Usage

CLI Commands

# Initialize with OAuth (interactive)
gsc-mcp init

# Initialize with service account
gsc-mcp init --service-account /path/to/key.json

# Initialize with full scope (for sitemap submission, URL inspection)
gsc-mcp init --scope full

# Check configuration and connectivity
gsc-mcp doctor
gsc-mcp doctor --verbose

# Start MCP server (stdio mode)
gsc-mcp run

# Start in HTTP mode (for debugging)
gsc-mcp run --http 3333

# View current configuration
gsc-mcp config

# Clear credentials
gsc-mcp logout

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gsc": {
      "command": "gsc-mcp",
      "args": ["run"]
    }
  }
}

VS Code (Copilot)

Add to your VS Code MCP settings (~/.vscode/mcp.json or workspace settings):

{
  "servers": {
    "gsc": {
      "command": "gsc-mcp",
      "args": ["run"],
      "type": "stdio"
    }
  }
}

Cursor

Add to your Cursor MCP config:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@appsyogi/gsc-mcp-server", "run"]
    }
  }
}

Available Tools

Search Analytics

Tool	Description
searchanalytics.query	Query search performance data with dimensions and filters
report.comparePeriods	Compare two time periods

Sitemaps

Tool	Description	Scope
sitemaps.list	List all sitemaps	readonly
sitemaps.get	Get sitemap details	readonly
sitemaps.submit	Submit a sitemap	full
sitemaps.delete	Delete a sitemap	full

URL Inspection

Tool	Description	Scope
urlInspection.inspect	Inspect a URL's indexing status	full
urlInspection.batchInspect	Inspect multiple URLs	full

SEO Opportunities

Tool	Description
opportunities.lowCtrHighPos	Find quick-win keywords (position 4-20, low CTR)
opportunities.cannibalization	Detect keyword cannibalization
report.weeklySummary	Generate weekly performance summary

Export

Tool	Description
export.csv	Export data as CSV
export.json	Export data as JSON

LLM Optimization (v0.2.0+)

All tools support parameters to reduce token consumption for LLM use cases:

Compact Response Format

Add format: "compact" to any tool for LLM-optimized output:

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2026-01-01",
  "endDate": "2026-01-28",
  "dimensions": ["query"],
  "format": "compact"
}

Compact format features:

• Short key names (imp instead of impressions, pos instead of position)
• CTR as percentage string ("5.41%" instead of 0.054123...)
• Natural language summary field
• URL prefixes stripped from page paths

Example compact response:

{
  "summary": "Top query 'example keyword' got 150 clicks at position 3.2",
  "rows": [
    {"key": "example keyword", "clicks": 150, "imp": 2800, "ctr": "5.36%", "pos": 3.2}
  ]
}

Date Rollup Granularity

For date dimension queries, use granularity to reduce row count:

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2025-07-01",
  "endDate": "2026-01-28",
  "dimensions": ["date"],
  "granularity": "weekly"
}

Options:

• daily — Default, returns daily data
• weekly — Aggregates by week (Monday-based)
• monthly — Aggregates by month
• auto — Picks based on date range (>90 days = monthly, >21 days = weekly)

Default Row Limits

Default rowLimit is 25 (optimized for LLM context windows). Use higher values when needed:

{
  "siteUrl": "sc-domain:example.com",
  "rowLimit": 100
}

Maximum: 25,000 rows.

Resources

The server exposes browsable resources:

• gsc://sites — List all properties
• gsc://sites/{siteUrl}/sitemaps — List sitemaps for a property

Scopes

GSC-MCP supports two permission levels:

Readonly (default)

• Search analytics queries
• List sitemaps
• SEO analysis tools

gsc-mcp init  # Uses readonly by default

Full

• Everything in readonly, plus:
• Submit/delete sitemaps
• URL inspection

gsc-mcp init --scope full

Configuration Files

GSC-MCP stores configuration in platform-specific locations:

Platform	Config Path
macOS	~/.config/gsc-mcp/
Linux	~/.config/gsc-mcp/
Windows	%APPDATA%/gsc-mcp/

Files:

• config.json — OAuth client ID/secret, scope settings
• cache.sqlite — Query cache and saved presets

Tokens are stored securely in the OS keychain when available.

Service Account Setup

For automated/server use, you can use a service account instead of OAuth:

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Add the service account email as an owner in Google Search Console
4. Initialize:

gsc-mcp init --service-account /path/to/key.json

API Quotas

Google Search Console API has a default quota of 1,200 queries per day. GSC-MCP includes:

• Automatic retry with exponential backoff
• Query caching to reduce API calls
• Pagination handling for large result sets

Examples

Find Quick-Win Keywords

Use gsc-mcp to find quick-win opportunities for my site https://example.com

Weekly Report

Generate a weekly performance summary for https://example.com

Compare Periods

Compare search performance for https://example.com between last week and the week before

Export Data

Export the top 1000 queries for https://example.com in the last 28 days as CSV

Development

# Clone the repo
git clone https://github.com/AppsYogi-com/gsc-mcp-server.git
cd gsc-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Test locally
node dist/cli/index.js doctor

License

MIT

Contributing

Contributions are welcome! Please open an issue or PR.

Credits

Built with:

• @modelcontextprotocol/sdk
• googleapis
• commander
• better-sqlite3