gsc-mcp — Google Search Console connector for Claude

A small self-hosted MCP server that exposes Search Console to Claude as a custom connector. Runs on any Node host behind your own domain (e.g. https://gsc.grobern.com).

Tools it exposes:

Google does not expose the Page Indexing report itself through the API. audit_indexing rebuilds it by inspecting each URL (2,000 inspections per property per day, 600/min).

1. Google side (once, ~10 min)

1. Google Cloud Console → create/select a project → APIs & Services → Library → enable Google Search Console API.

2. IAM & Admin → Service Accounts → Create service account (any name, no roles needed).

3. Open it → Keys → Add key → JSON. Download the file. Keep it private.

4. In Search Console → property → Settings → Users and permissions → Add user, paste the service account's email (…@…iam.gserviceaccount.com) with Full permission (Full is required for URL Inspection). Do this for every property you want Claude to see.

For thesurferweligama.com the property is most likely sc-domain:thesurferweligama.com (Domain property) or https://thesurferweligama.com/ (URL-prefix). list_sites will tell you.

Related MCP server: google-search-console

2. Run it

cp .env.example .env         # fill in MCP_SECRET and GOOGLE_SERVICE_ACCOUNT_JSON
npm install
npm run build
npm start                    # http://localhost:3000/mcp/<MCP_SECRET>

Generate a secret with openssl rand -hex 24. GOOGLE_SERVICE_ACCOUNT_JSON accepts the raw JSON on one line, or base64 -w0 key.json output if your host mangles newlines.

Health check: GET /health → {"ok":true}.

3. Use it in Claude Code (free, no hosting)

Hosting is only needed for claude.ai custom connectors. Claude Code can spawn the server itself over stdio — no port, no MCP_SECRET, no deployment:

npm install && npm run build
claude mcp add gsc --scope user -- node --env-file=/abs/path/to/.env /abs/path/to/dist/stdio.js
claude mcp list        # gsc - ✔ Connected

Only GOOGLE_SERVICE_ACCOUNT_JSON (and optionally DEFAULT_SITE) are read in this mode.

4. Put it on your domain

Any of these work; the server is stateless so it scales horizontally and needs no sticky sessions.

Docker / VPS (Coolify, Dokploy, plain docker):

docker build -t gsc-mcp .
docker run -d --env-file .env -p 3000:3000 gsc-mcp

Point gsc.yourdomain.com at it with an HTTPS reverse proxy (Caddy: gsc.yourdomain.com { reverse_proxy localhost:3000 }).

Render (one click):

Reads render.yaml and only prompts for MCP_SECRET and GOOGLE_SERVICE_ACCOUNT_JSON.

Railway / Fly: deploy the repo, set the three env vars, attach a custom domain in the dashboard, done.

Vercel: the app uses a long-lived Express listener, so Vercel serverless is not a drop-in. Use one of the above, or ask Claude to port the two files into a Next.js route handler with mcp-handler.

5. Add it to Claude (hosted connector)

Claude.ai → Settings → Connectors → Add custom connector

• Name: Google Search Console

• URL: https://gsc.yourdomain.com/mcp/<MCP_SECRET>

• Authentication: none (the secret in the path is the credential — treat the URL like a password)

Then enable it in the chat and ask, for example:

Audit page indexing for thesurferweligama.com using the sitemap at https://thesurferweligama.com/sitemap.xml

Troubleshooting

"Error 400: redirect_uri_mismatch" / "Access blocked: This app's request is invalid"

You created an OAuth client ID instead of a service account. This connector never uses OAuth — there is no browser sign-in and no redirect URI. Delete the OAuth client (it isn't needed) and follow step 1 above: IAM & Admin → Service Accounts, not APIs & Services → Credentials → OAuth client ID.

A correct key file starts with "type": "service_account" and contains "private_key". An OAuth client file contains "client_id", "client_secret" and "redirect_uris" — that one will not work here.

Tools return "The caller does not have permission"

The service account email is not a user on the property, or has less than Full permission. Add it in Search Console → Settings → Users and permissions.

Security notes

• Anyone with the full URL can read your Search Console data. Rotate MCP_SECRET if it leaks; the server 404s on any other path.

• The service account only has the Search Console scope; it cannot touch anything else in your Google account.

• Read-only by design: no tool submits sitemaps, requests indexing or changes settings.

Development

npm run dev   # tsx watch, hot reload