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

CLAUDE.md — mcp-google-search-console

MCP server for the Google Search Console API (TypeScript, stdio). Mostly reads plus a few idempotent mutations: tools cover properties (sites), sitemaps, the Search Analytics performance query and URL index inspection; raw_request is the escape hatch. The server talks to https://searchconsole.googleapis.com (one host, two surfaces: webmasters/v3 and v1) with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN, mostly for testing).

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY check (lists the account's properties)

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_SEARCH_CONSOLE_CLIENT_ID + GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET + GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN; optional GOOGLE_SEARCH_CONSOLE_API_BASE, GOOGLE_SEARCH_CONSOLE_TIMEOUT_MS, GOOGLE_SEARCH_CONSOLE_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (opens with the historical startup error verbatim, then names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); request() resolves the path against the base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET, and throws GoogleSearchConsoleError(status, body) surfacing Google's envelope with the first reason. seg() URL-encodes siteUrl/feedpath path segments — full URLs and sc-domain: values embedded in paths. searchAnalytics() wraps flat filters into the single AND dimensionFilterGroups group; mutations (sites.add/delete, sitemaps.submit/delete) return an empty body on success, wrapped as { ok: true, ... } — never parse it as JSON.
• src/tools/sites.ts — list_sites, get_site, add_site, delete_site. src/tools/sitemaps.ts — list_sitemaps, get_sitemap, submit_sitemap, delete_sitemap. src/tools/analytics.ts — search_analytics and its sugar get_top_queries (dimensions=["query"] + optional page/country/device filters). src/tools/inspection.ts — inspect_url. src/tools/raw.ts — raw_request (GET/POST/PUT/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/DESTRUCTIVE/RAW) and shared zod schema factories (siteUrlSchema, feedpathSchema, ymdDate).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth_config) — never a variable's name or value.