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):

Platform	Install
macOS	xcode-select --install
Windows	Visual Studio Build Tools — select "Desktop development with C++"
Linux (Debian/Ubuntu)	sudo apt-get install build-essential python3
Linux (Fedora/RHEL)	sudo dnf groupinstall "Development Tools" && sudo dnf install python3

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

Tool	Description
list_sites	List all verified GSC properties
get_site	Get details for a specific site
query_search_analytics	Query clicks, impressions, CTR, position with dimensions/filters/pagination
inspect_url	Check URL index/crawl status (2,000/day limit)
list_sitemaps	List sitemaps for a site
get_sitemap	Get sitemap details
submit_sitemap	Submit a new sitemap
delete_sitemap	Remove a sitemap from GSC
switch_account	Re-authenticate with a different Google account (OAuth only)

Data Sync

Tool	Description
sync_search_data	Fetch all performance data into local SQLite cache. Incremental by default. Required before analysis tools.

Analysis Tools

Tool	Description
find_low_hanging_fruit	Find queries ranking 2-20 with high impressions but low CTR, scored by untapped potential
detect_cannibalization	Detect queries ranking on 2+ URLs using HHI scoring with action recommendations
find_trending_queries	Find queries with biggest growth/decline (period-over-period or year-over-year)
find_trending_pages	Find pages with biggest growth/decline with impact scoring
analyze_traffic_drop	Diagnose traffic drops across 5 views: site-level, GBP vs organic, groups, segments, brand vs non-brand
get_group_performance	Aggregated metrics broken down by named groups with share percentages

Group Management

Tool	Description
create_group	Create a group with OR/AND/NOT regex rules for URL segments or query groups
list_groups	List all groups, optionally filtered by dimension
get_group	Get group details including rules
update_group	Update group description and/or rules
delete_group	Delete a group and its rules
test_group	Test a group against cached data — match count, rate, samples

Auto-Discovery

Tool	Description
discover_query_groups	Auto-cluster queries using word overlap, n-gram similarity, and page co-occurrence
promote_cluster_to_group	Convert a discovered cluster into a named group
auto_segment_pages	Auto-create URL segment groups from page URL patterns
auto_group_queries	Auto-create query groups: brand, topic n-grams, intent modifiers

Resources

URI	Description
sites://list	All verified sites (auto-discovery)

Prompts

Name	Description
seo_performance_analysis	Guided full SEO review (queries, pages, devices, trends)
index_coverage_check	Systematic URL indexation report

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

Variable	Required	Default	Description
GSC_AUTH_MODE	No	Auto-detected	oauth or service_account. Auto-detected from which credentials are set.
GSC_OAUTH_CLIENT_ID	OAuth	—	OAuth client ID
GSC_OAUTH_CLIENT_SECRET	OAuth	—	OAuth client secret
GSC_OAUTH_REFRESH_TOKEN	No	—	Skip browser flow with a pre-existing token
GSC_SERVICE_ACCOUNT_KEY_PATH	Service acct	—	Path to JSON key file
GSC_API_SCOPES	No	webmasters.readonly	Override scopes (comma-separated)
GSC_LOG_LEVEL	No	info	debug / info / warn / error
GSC_TOKEN_PATH	No	~/.gsc-mcp/tokens.json	Custom token storage path
GSC_DB_PATH	No	~/.gsc-mcp/data.db	Custom SQLite database path

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