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.

Installation

uvx (recommended, zero-install)

Terminal

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

Terminal

pip install mcp-google-search-console-crunchtools

Container (Podman/Docker)

bash

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

OAuth Setup

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

Option A: Browser-Based OAuth (Recommended)

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

Go to Google Cloud Console
Create a new project (or select an existing one)
Navigate to APIs & Services > Library
Search for Google Search Console API and click Enable
Navigate to APIs & Services > Credentials
Click + CREATE CREDENTIALS > OAuth client ID
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
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)
Click Create — copy the Client ID and Client Secret

Step 2: Configure and Start

Create an env file:

bash

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:

bash

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.

Manual OAuth flow

server.ts

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"

Open the URL in your browser, sign in, and click Allow
Copy the code= value from the redirect URL
Exchange the code:

Terminal

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

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:

File-based credentials from GSC_CREDENTIALS_DIR/credentials.json (written by the browser-based flow)
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

bash

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