Skip to main content
Glama
mcp-google-search-console-crunchtools

mcp-google-search-console-crunchtools

by crunchtools

mcp-google-search-console-crunchtools

Secure MCP server for Google Search Console. Query search analytics (clicks, impressions, CTR, position), manage sitemaps, inspect URL indexing status, and manage site properties.

CI PyPI License: AGPL v3

Installation

claude mcp add mcp-google-search-console-crunchtools \
    --env GSC_CLIENT_ID=your_client_id \
    --env GSC_CLIENT_SECRET=your_client_secret \
    --env GSC_REFRESH_TOKEN=your_refresh_token \
    -- uvx mcp-google-search-console-crunchtools

pip

pip install mcp-google-search-console-crunchtools

Container (Podman/Docker)

podman run -d -p 8017:8017 \
    --env-file ~/.config/mcp-env/mcp-google-search-console.env \
    quay.io/crunchtools/mcp-google-search-console \
    --transport streamable-http --host 0.0.0.0

Related MCP server: Google Search Console MCP Server

OAuth Setup

This server supports two authentication methods: browser-based OAuth (recommended) and environment variable (fallback).

Browser-based OAuth handles token exchange automatically. When credentials expire, visit the /auth URL and click through Google's consent screen — no manual code exchange needed.

Step 1: Create a Google Cloud OAuth App

  1. Go to Google Cloud Console

  2. Create a new project (or select an existing one)

  3. Navigate to APIs & Services > Library

  4. Search for Google Search Console API and click Enable

  5. Navigate to APIs & Services > Credentials

  6. Click + CREATE CREDENTIALS > OAuth client ID

  7. If prompted, configure the OAuth consent screen first:

    • User type: External (or Internal if using Google Workspace)

    • App name: anything (e.g., "MCP Search Console")

    • Scopes: add https://www.googleapis.com/auth/webmasters

    • Test users: add your Google account email

  8. Back on Create OAuth client ID:

    • Application type: Web application

    • Name: anything (e.g., "MCP Search Console")

    • Authorized redirect URIs: add your server's callback URL (e.g., https://mcp-gsc.example.com/oauth2callback)

  9. Click Create — copy the Client ID and Client Secret

Step 2: Configure and Start

Create an env file:

cat > ~/.config/mcp-env/mcp-google-search-console.env << 'EOF'
GSC_CLIENT_ID=your_client_id
GSC_CLIENT_SECRET=your_client_secret
GSC_CREDENTIALS_DIR=/data
GSC_OAUTH_REDIRECT_URI=https://mcp-gsc.example.com/oauth2callback
EOF
chmod 600 ~/.config/mcp-env/mcp-google-search-console.env

Start the server with a persistent volume for credentials:

podman run -d -p 8017:8017 \
    --env-file ~/.config/mcp-env/mcp-google-search-console.env \
    -v mcp-gsc-data:/data:Z \
    quay.io/crunchtools/mcp-google-search-console \
    --transport streamable-http --host 0.0.0.0

Step 3: Authenticate

Visit https://mcp-gsc.example.com/auth in your browser. You'll be redirected to Google's consent screen. Grant access and the server will save credentials automatically.

When tokens expire, any tool call will return the /auth URL. Click it to re-authenticate — no container restart needed.

Option B: Environment Variable (Fallback)

If you prefer static credentials or can't expose a callback URL, set GSC_REFRESH_TOKEN in your env file. See the manual OAuth flow below.

export GSC_CLIENT_ID="your_client_id_here"
export GSC_CLIENT_SECRET="your_client_secret_here"

echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GSC_CLIENT_ID}&redirect_uri=http://127.0.0.1&response_type=code&scope=https://www.googleapis.com/auth/webmasters&access_type=offline&prompt=consent"
  1. Open the URL in your browser, sign in, and click Allow

  2. Copy the code= value from the redirect URL

  3. Exchange the code:

curl -s -X POST https://oauth2.googleapis.com/token \
    -d "client_id=${GSC_CLIENT_ID}" \
    -d "client_secret=${GSC_CLIENT_SECRET}" \
    -d "code=PASTE_CODE_HERE" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=http://127.0.0.1" | python3 -m json.tool
  1. Copy the refresh_token from the response and add GSC_REFRESH_TOKEN=... to your env file.

How it works at runtime

The server checks for credentials in this order:

  1. File-based credentials from GSC_CREDENTIALS_DIR/credentials.json (written by the browser-based flow)

  2. Environment variable GSC_REFRESH_TOKEN (fallback)

On each API call, the server exchanges the refresh token for a short-lived access token (~1 hour), cached in memory and refreshed automatically. Updated tokens are persisted to the credentials file for reuse across container restarts.

Available Tools (10)

Category

Count

Tools

Sites

4

list_sites, get_site, add_site, delete_site

Search Analytics

1

query_search_analytics

Sitemaps

4

list_sitemaps, get_sitemap, submit_sitemap, delete_sitemap

URL Inspection

1

inspect_url

Security

  • OAuth2 credentials stored as SecretStr (never logged)

  • File-based credentials written with 0o600 permissions (atomic writes)

  • Automatic token scrubbing from error messages

  • Pydantic input validation with extra="forbid"

  • No filesystem access, shell execution, or code evaluation

  • TLS certificate validation (httpx default)

  • Request timeouts and response size limits

  • Built on Hummingbird container images

See SECURITY.md for the full security design document.

Development

uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v
gourmand --full .
podman build -f Containerfile .

License

AGPL-3.0-or-later

Available Tools

10 tools
add_site_toolAdd Site ToolC

Add a site to Search Console.

Inputs: site_url (required). Returns: object

delete_sitemap_toolDelete Sitemap ToolC

Remove a sitemap from Search Console.

Inputs: feedpath (required), site_url (required). Returns: object

delete_site_toolDelete Site ToolC

Remove a site from Search Console.

Inputs: site_url (required). Returns: object

get_sitemap_toolGet Sitemap ToolC
Read-only

Get details for a specific sitemap.

Inputs: feedpath (required), site_url (required). Returns: object

get_site_toolGet Site ToolB
Read-only

Get details for a specific Search Console property.

Inputs: site_url (required). Returns: object

inspect_url_toolInspect Url ToolA
Read-only

Inspect a URL's index status in Google Search.

Returns detailed information about how Google sees a URL including index coverage, crawl status, mobile usability, and rich results.

Inputs: site_url (required), inspection_url (required), language_code. Returns: object

list_sitemaps_toolList Sitemaps ToolB
Read-only

List all sitemaps submitted for a site.

Inputs: site_url (required). Returns: object

list_sites_toolList Sites ToolA
Read-only

List all Search Console properties accessible by the authenticated user.

Inputs: no named parameters. Returns: object

query_search_analytics_toolQuery Search Analytics ToolA
Read-only

Query search traffic data with filters and dimensions.

Returns clicks, impressions, CTR, and average position grouped by the requested dimensions. Use this to analyze search performance for specific pages, queries, countries, devices, or date ranges.

Inputs: end_date (required), site_url (required), start_date (required), row_limit, +6 more. Returns: object

submit_sitemap_toolSubmit Sitemap ToolC

Submit a sitemap for crawling.

Inputs: feedpath (required), site_url (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action: site management (list/add/get/delete), sitemap management (list/get/submit/delete), URL inspection, and search analytics querying. There is no meaningful overlap between tools, and descriptions make boundaries explicit.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun_tool pattern, such as list_sites_tool, add_site_tool, get_sitemap_tool, and query_search_analytics_tool. Singular/plural usage is predictable for single-resource versus list operations.

    Tool Count5/5

    Ten tools is well-scoped for the Google Search Console domain. Every tool corresponds to a distinct API capability, and there are no redundant or filler tools.

    Completeness5/5

    The surface covers the core Search Console operations: site CRUD, sitemap list/get/submit/delete, URL inspection, and search analytics querying. This aligns closely with the underlying API and leaves no obvious dead ends for normal workflows.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Google Search Console API that enables querying search analytics, managing sites, inspecting URLs, and supporting domain delegation via service accounts.
      36 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      This MCP server provides LLMs with programmatic access to Google Search Console data and functionality, including search analytics, sitemap management, site management, and URL inspection.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Google Search Console, enabling querying search performance, listing properties, and inspecting URL indexing status from MCP-compatible clients.
      4
      38 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for Google Search Console data, enabling search analytics, URL inspection, indexing diagnostics, and sitemap management through MCP clients.
      13 npm
      1
      MIT