GSC MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop (and other MCP clients) to the Google Search Console API — query search analytics, inspect URLs, manage sitemaps, and compare performance across time periods.

Based on MCP-GSC by Amin Foroutan, with enhancements for lazy imports, data state control, multi-filter support, and additional tools.

Features

20 Search Console Tools

Search Analytics:

URL Inspection:

Sitemap Management:

Property Management:

Built-in Reliability

• Dual auth — OAuth (interactive) and service account (headless) with automatic fallback

• Lazy imports — defers heavy Google client libraries for fast MCP handshake

• Data state control — choose between fresh data (all, matches GSC dashboard) or confirmed data (final)

• Multi-filter support — AND logic across dimensions via JSON filter arrays

Related MCP server: GSC MCP Server

Quick Start

Prerequisites

• Python 3.10+

• A Google Cloud project with the Search Console API enabled

• Claude Desktop (or any MCP-compatible client)

Authentication Options

Option A: Service Account (Headless — recommended for servers)

1. Create a Google Cloud service account

2. Enable the Search Console API in your project

3. Download the service account JSON key file

4. In GSC: go to Settings > Users and permissions and add the service account email as a user

Option B: OAuth (Interactive — recommended for local use)

1. Create OAuth credentials in Google Cloud Console

2. Download the client secrets JSON as client_secrets.json

3. Place it in the gsc-mcp/ directory

4. On first run, a browser window opens for Google login

Installation

git clone https://github.com/luminarylane/gsc-mcp.git
cd gsc-mcp
pip install -r requirements.txt

Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "gsc": {
      "command": "python",
      "args": ["/path/to/gsc-mcp/gsc_server.py"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/path/to/service_account_credentials.json"
      }
    }
  }
}

Environment variables:

*At least one authentication method must be configured.

Alternatively, place service_account_credentials.json or client_secrets.json in the gsc-mcp/ directory.

Usage Examples

Once configured, ask Claude to:

• "List my Search Console properties"

• "What are the top queries for my site this month?"

• "Show me the top pages by clicks for the last 90 days"

• "Is this URL indexed? Check https://example.com/my-page"

• "Compare search performance: last 28 days vs the 28 days before"

• "Check indexing issues for these URLs" (paste a list)

• "Submit my sitemap at https://example.com/sitemap.xml"

• "Show traffic sources by country and device"

Data Freshness

By default, the server uses dataState: "all" which includes fresh/unconfirmed data and matches the GSC dashboard. Set GSC_DATA_STATE=final for confirmed-only data (lags 2-3 days). You can also override per-call via the data_state parameter in get_advanced_search_analytics.

Troubleshooting

Property not found (404)

The site_url must exactly match what GSC shows. Run list_properties first. Domain properties use the format sc-domain:example.com, not a full URL.

Permission denied (403)

The authenticated account needs access to the property. For service accounts, add the email in GSC Settings > Users and permissions.

Authentication failed

• Service account: Check GSC_CREDENTIALS_PATH points to a valid JSON key file

• OAuth: Delete token.json and re-run to trigger a fresh login, or use the reauthenticate tool

Contributing

1. Fork the repo

2. Create a feature branch (git checkout -b feat/my-feature)

3. Make changes and test locally

4. Submit a pull request

License

MIT License — see LICENSE for details.

Acknowledgments

• Amin Foroutan for the original MCP-GSC tool

• Anthropic for the MCP specification

• Google Search Console API for the underlying API