Google Search Console MCP Server

An MCP server that gives Claude direct access to your Google Search Console data — search performance, URL indexation, sitemaps, and built-in SEO analysis tools including trending queries, cannibalization detection, traffic drop diagnostics, and automated query/page grouping.

Prerequisites

• Node.js >= 18.0.0
• A C++ compiler (required by the better-sqlite3 dependency):

Quick Start

git clone https://github.com/serpfire/gsc-mcp-server.git
cd gsc-mcp-server
npm install

1. Create Google OAuth credentials

1. Go to Google Cloud Console
2. Create an OAuth 2.0 Client ID (type: Desktop app)
3. Enable the Google Search Console API in your project

2. Authenticate

GSC_OAUTH_CLIENT_ID=your-client-id \
GSC_OAUTH_CLIENT_SECRET=your-client-secret \
npm run setup

This opens your browser to sign in with Google. Tokens are stored at ~/.gsc-mcp/tokens.json and auto-refresh. Run setup again anytime to switch accounts.

3. Add to Claude Code

claude mcp add --transport stdio gsc -s user \
  -e GSC_OAUTH_CLIENT_ID=your-client-id \
  -e GSC_OAUTH_CLIENT_SECRET=your-client-secret \
  -- node /absolute/path/to/gsc-mcp-server/src/index.js

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "gsc": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gsc-mcp-server/src/index.js"],
      "env": {
        "GSC_OAUTH_CLIENT_ID": "your-client-id",
        "GSC_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Service Account Alternative

For automation or server-to-server use:

{
  "env": {
    "GSC_AUTH_MODE": "service_account",
    "GSC_SERVICE_ACCOUNT_KEY_PATH": "/path/to/key.json"
  }
}

Tools

Core GSC Tools

Data Sync

Analysis Tools

Group Management

Auto-Discovery

Resources

Prompts

Example Queries

• "List my Search Console sites"
• "Show top 20 queries for sc-domain:example.com last 7 days"
• "Compare mobile vs desktop for https://example.com/"
• "Check if https://example.com/new-page is indexed"
• "Show sitemaps for sc-domain:example.com"
• "Sync data for sc-domain:example.com and find low-hanging fruit"
• "Detect keyword cannibalization on sc-domain:example.com"
• "Show trending queries for sc-domain:example.com last 28 days"
• "Auto-create query groups for sc-domain:example.com"

Architecture

src/
├── index.js                          # Entry: auth -> client -> db -> server -> stdio
├── server.js                         # McpServer factory
├── auth/
│   ├── index.js                      # Auth factory (auto-detects mode from env)
│   ├── service-account.js            # Service account key file auth
│   ├── oauth.js                      # Browser flow + token persistence + auto-recovery
│   ├── token-store.js                # ~/.gsc-mcp/tokens.json
│   └── setup.js                      # Standalone setup script
├── gsc/                              # Pure GSC API wrappers (no MCP knowledge)
│   ├── client.js
│   ├── sites.js
│   ├── search-analytics.js
│   ├── sitemaps.js
│   └── url-inspection.js
├── db/
│   ├── connection.js                 # SQLite setup with WAL mode
│   └── schema.js                     # Migrations
├── analysis/                         # SEO analysis engine (uses local SQLite)
│   ├── sync.js                       # GSC API -> SQLite incremental sync
│   ├── low-hanging-fruit.js          # Opportunity scoring
│   ├── cannibalization.js            # HHI-based detection
│   ├── trending.js                   # PoP / YoY trending queries & pages
│   ├── traffic-drop.js              # Multi-view drop diagnostics
│   ├── group-performance.js          # Group-level aggregation
│   ├── auto-segment.js              # Automatic URL segmentation
│   ├── auto-group.js                # Automatic query grouping
│   ├── shared.js                     # Shared SQL helpers
│   ├── groups/
│   │   ├── manager.js                # CRUD for groups + rules
│   │   ├── compiler.js               # OR/AND/NOT rule compilation
│   │   └── matcher.js                # Regex matching engine
│   └── semantic/
│       ├── discover.js               # Cluster discovery orchestrator
│       ├── clustering.js             # Connected components algorithm
│       ├── similarity.js             # Multi-signal similarity scoring
│       └── labeler.js                # Cluster naming
├── tools/
│   ├── definitions.js                # Core GSC tools (declarative)
│   ├── analysis-definitions.js       # Analysis tools (declarative)
│   ├── middleware.js                  # Rate limiting + error handling wrapper
│   ├── auth.js                       # switch_account tool
│   └── index.js                      # Registration loop
├── resources.js                      # sites://list resource
├── prompts.js                        # SEO analysis + index check prompts
└── utils/
    ├── logger.js                     # stderr-only (stdout = MCP protocol)
    ├── errors.js                     # Google API error -> MCP error
    ├── constants.js                  # Scopes, rate limits, defaults
    ├── rate-limiter.js               # Sliding window
    └── open-url.js                   # Cross-platform browser opener

Two-layer separation: gsc/ knows nothing about MCP. tools/ knows nothing about Google's API. analysis/ operates on local SQLite data. Each layer is independently testable.

Environment Variables

Debugging

Launch the MCP Inspector for interactive testing:

npm run inspect

Windows note: The inspect script uses bash. Run it from Git Bash, WSL, or replace with:

npx @modelcontextprotocol/inspector node src/index.js