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

Quick Start

Prerequisites

• Python 3.11+
• 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

# Run without a global install
uvx --from luminarylane-gsc-mcp luminarylane-gsc-mcp

Or install the package with pip install luminarylane-gsc-mcp.

Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "gsc": {
      "command": "uvx",
      "args": ["--from", "luminarylane-gsc-mcp", "luminarylane-gsc-mcp"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/path/to/service_account_credentials.json"
      }
    }
  }
}

Environment variables:

*At least one authentication method must be configured.

For local development only, credentials may be stored in files excluded by .gitignore; never commit them. Prefer the explicit environment-variable paths above.

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