google-search-console-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Docs

• docs/architecture.md: full architectural reference (API clients, GA4 protobuf pattern, batch implementation, retry/quota internals, v0.5 additions)
• docs/google-setup.md: GCP project setup, enabling APIs, service account creation, GSC and GA4 permission configuration
• docs/starter-prompt.md: ready-to-use audit prompts for Claude Desktop users (full audit, quick check, single-page, reindexing, CrUX, schema)

Commands

# Requires Python 3.11+
python3 --version  # must be 3.11 or higher

# Install (dev mode with test deps)
pip install -e ".[dev]"

# Run the MCP server
gsc-mcp
# or
python -m gsc_mcp.server

# Run all tests (339 tests, fully mocked)
pytest tests/ -v

# Run a single test file
pytest tests/test_analytics.py -v

# Run a specific test by name
pytest tests/ -k "test_submit_batch" -v

Architecture

Entry point: src/gsc_mcp/server.py creates a FastMCP("gsc-mcp") instance and registers all 61 tools by iterating registry.TOOLS. Dynamic: adding a function to registry.py is enough to register it in both the MCP server and the CLI.

Registry (src/gsc_mcp/registry.py): imports all 61 tool functions and exposes TOOLS: dict[str, Callable[..., str]]. An assert at import time verifies set(TOOLS) == set(_ALL_TOOLS) from properties.py, so any mismatch fails loudly at startup.

CLI (src/gsc_mcp/cli.py): shell frontend that generates 61 subcommands from TOOLS by introspection. All-flags (no positionals). list[dict] params take a JSON string. Sets GSC_NO_BROWSER=1 at startup to prevent accidental OAuth browser popups.

Auth layer (auth.py): Three separate credential pairs (GSC API searchconsole/v1, Indexing API indexing/v3, GA4 analytics.readonly). Resolution order: if GSC_SERVICE_ACCOUNT_PATH is set, use service account credentials. Otherwise, fall through to OAuth with token cached as JSON (not pickle) at the OS user data dir (~/Library/Application Support/gsc-mcp/ on macOS). Token files are written chmod 0o600; the directory is created with 0o700. get_ga4_property_id(override=None) accepts an optional override string that bypasses GA4_PROPERTY_ID, enabling per-call multi-property support.