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:

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Search Console API:
- Go to "APIs & Services" → "Library"
- Search for "Google Search Console API"
- Click "Enable"
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"
Copy the Client ID and Client Secret
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

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:

Create a service account in Google Cloud Console
Download the JSON key file
Add the service account email as an owner in Google Search Console
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: