mcp-server-google-search-console

Community-built MCP server for the Google Search Console API. Provides search analytics, performance summaries, URL inspection, sitemap management, and property listing through the Model Context Protocol.

Features

• 9 tools covering search analytics, performance summaries, URL inspection, sitemap management, and property listing
• 3 prompts for guided multi-step SEO workflows
• 2 resources for automatic property and sitemap discovery
• Service Account & OAuth — choose headless or interactive authentication
• Read-only by default — write tools are only registered when write scope is configured
• Safety gates — delete_sitemap requires explicit confirm: true
• Minimal dependencies — only @modelcontextprotocol/sdk and zod

Quick Start

1. Set Up Credentials

Service Account (recommended for servers & CI):

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Google Search Console API
4. Create a Service Account and download the JSON key file
5. In Google Search Console, add the service account email as a user to your properties

OAuth (recommended for personal use):

1. In Google Cloud Console, create OAuth 2.0 Client ID (type: Desktop app)
2. Download the client credentials JSON
3. Set GSC_OAUTH_CLIENT_FILE — the server will open a browser for consent on first run
4. Tokens are cached at ~/.config/gsc-mcp/oauth-token.json (or GSC_OAUTH_TOKEN_FILE)

2. Configure Your Client

claude mcp add google-search-console \
  -e GSC_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account-key.json \
  -- npx -y mcp-server-google-search-console

Or add to .mcp.json manually:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-search-console"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json"
      }
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-search-console"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json"
      }
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-search-console"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json"
      }
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-search-console"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json"
      }
    }
  }
}

docker build -t gsc-mcp .

{
  "mcpServers": {
    "google-search-console": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GSC_SERVICE_ACCOUNT_KEY_FILE=/key.json",
        "-v", "/path/to/service-account-key.json:/key.json:ro",
        "gsc-mcp"
      ]
    }
  }
}

Tools

Always available (read-only scope)

| Tool | Description | |------|-------------| | list_sites | List all GSC properties accessible by the current credentials | | get_site | Get details for a specific property (permission level, verification) | | get_search_analytics | Query search performance data with dimensions, filters, date ranges, and comparison mode | | get_performance_summary | Quick performance overview: current vs previous period metrics, deltas, and top 10 queries in a single call | | inspect_url | Check a URL's indexing status, mobile usability, and rich results | | batch_inspect_urls | Inspect multiple URLs concurrently (up to 20) with a single call | | list_sitemaps | List all sitemaps for a property with aggregated health summary |

Write scope required

These tools are only registered when GSC_SCOPES includes the full write scope. They do not appear in the tool list otherwise.

| Tool | Description | |------|-------------| | submit_sitemap | Submit a sitemap to Google | | delete_sitemap | Delete a sitemap (requires confirm: true safety gate) |

Prompts

Guided multi-step SEO workflows that guide LLMs through structured analysis.

| Prompt | Parameters | Description | |--------|------------|-------------| | seo_performance_analysis | site_url, period (7d/28d/90d) | 5-step analysis: Top Queries → Top Pages → Device Split → Country Split → Trends. Produces a structured report with actionable insights. | | index_coverage_check | site_url, urls (comma-separated) | Batch URL inspection with structured coverage report — flags indexing issues, canonical mismatches, and mobile problems. | | content_opportunity_analysis | site_url | Full-funnel analysis: Low-Hanging Fruit (positions 5–20), Keyword Cannibalization detection, and Trending queries via comparison mode. |

Resources

| URI | Description | |-----|-------------| | sites://list | Auto-discovery of all GSC properties accessible with current credentials. Enables LLMs to discover available sites without calling list_sites first. | | sitemaps://{site_url} | Sitemaps for a specific property (e.g. sitemaps://sc-domain:example.com) with health summary, errors, warnings, and index rates. |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GSC_SERVICE_ACCOUNT_KEY_FILE | * | Path to service account JSON key file | | GSC_SERVICE_ACCOUNT_KEY | * | Inline service account JSON (alternative to file) | | GSC_OAUTH_CLIENT_FILE | * | Path to OAuth client credentials JSON (Desktop app type) | | GSC_OAUTH_TOKEN_FILE | No | Custom path for cached OAuth tokens (default: ~/.config/gsc-mcp/oauth-token.json) | | GSC_SCOPES | No | OAuth scope. Default: webmasters.readonly. Set to https://www.googleapis.com/auth/webmasters for write access |

* Auth priority: OAuth (GSC_OAUTH_CLIENT_FILE) > Service Account (GSC_SERVICE_ACCOUNT_KEY_FILE or GSC_SERVICE_ACCOUNT_KEY). At least one must be configured.

Development

npm install      # Install dependencies
npm run build    # Build
npm run dev      # Watch mode
npm test         # Run tests

License

MIT

Note: This is an unofficial community project. It is not affiliated with or endorsed by Google.

Built by Tobias Hein at artaxo — a digital marketing agency specializing in AI Search Optimization.