Google Search Console MCP

An MCP server that gives Claude, Cursor, Codex and any other MCP client clean access to Google Search Console: search analytics, question-shaped queries, ranking opportunities, URL inspection and sitemaps.

It runs on your machine, talks to Google with your own credentials, and sends nothing anywhere else. No telemetry.

Why this one

Every GSC MCP server wraps the same API. The differences are in the details that decide whether the model gets numbers it can trust:

• Dates are resolved on the server. Ask for last_28_days and the server computes the range in the property's timezone (America/Los_Angeles, the one Search Console itself uses). That removes both the UTC off-by-one and the dates models make up when asked about "last month".

• Windows end where the data ends. Search Console reports lag 2-3 days. Preset ranges snap to the newest date that has rows, so trends are not biased by trailing empty days. Opt out with anchor=today.

• Fresh data by default. Requests use dataState=all, matching the numbers you see in the Search Console UI. Use data_state=final for stable reporting.

• Comparisons are computed server-side. compare=previous_period or same_period_last_year (shifted 364 days so weekdays align) returns one merged table with clicks_change, position_change and is_new per row. The model never has to join two tables, a task LLMs are unreliable at.

• Compact responses. One text block of minified JSON per call, paginated with limit/offset/has_more, nothing sent twice. Long sessions keep their context for rows.

• Question-shaped queries in 10 languages. A dedicated tool finds searches phrased as questions (what/how/why/compare/…) via regex filters that run inside Search Console itself: English, Spanish, French, Portuguese, Russian, Arabic, Hindi, Bengali, Indonesian and Chinese.

• Read-only by default. Sitemap submit/delete exist but only work when you start the server with --enable-writes.

• Errors that name the fix. Every failure message says what to do next, and gsc-mcp doctor checks the whole chain end to end.

Related MCP server: GSC MCP Server

Quick start

Requires Node.js 20+ and a one-time Google sign-in:

npx -y @eduardmur/gsc-mcp login   # guided setup, ~2 minutes
npx -y @eduardmur/gsc-mcp doctor  # verify everything works

login walks you through creating your own free Google OAuth client (you control the credentials; nothing is shared with anyone) and signs you in via your browser. Details and alternatives in docs/auth-oauth.md, docs/auth-service-account.md and docs/auth-adc.md.

Then add the server to your client:

Claude Code

claude mcp add gsc -- npx -y @eduardmur/gsc-mcp

Claude Desktop: add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@eduardmur/gsc-mcp"]
    }
  }
}

Cursor: add to .cursor/mcp.json:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@eduardmur/gsc-mcp"]
    }
  }
}

Codex CLI

codex mcp add gsc -- npx -y @eduardmur/gsc-mcp

Now ask things like:

Which queries gained and lost the most clicks this week on example.com?

What questions do people ask that we rank for but never answer on a dedicated page?

Find cannibalization on sc-domain:example.com and tell me which page should win each query.

Tools

Full parameter reference: docs/tools.md.

Prompts

Six ready-made recipes ship with the server and appear as slash commands in clients that support MCP prompts (in Claude Code: /gsc:weekly-report etc.):

weekly-report · content-decay · striking-distance · cannibalization-check · questions-to-content · indexing-triage

Each one is a step-by-step plan: which tools to call with which arguments, and what to deliver.

CLI

gsc-mcp             # serve MCP on stdio (what your client runs)
gsc-mcp login       # connect a Google account (guided)
gsc-mcp logout      # remove saved tokens
gsc-mcp doctor      # 6 end-to-end checks: node, credentials, token, properties, query, freshness

Flags: --enable-writes, --key-file <path>, --client <path>, --no-open.

Tokens are stored in ~/.config/gsc-mcp/tokens.json (0600). The only Google scope requested is webmasters.readonly.

Prefer a hosted setup?

If you'd rather skip local setup, or want AI-visibility data next to your Search Console numbers (how ChatGPT, Perplexity, Gemini and AI Overviews talk about your brand), Searcherries runs a hosted MCP with one-click OAuth: GSC, Bing Webmaster Tools, GA4 AI traffic and tracked AI answers in one server. The two are independent: neither needs the other. See docs/hosted.md.

Troubleshooting

Run gsc-mcp doctor first; it pinpoints the failing step. Common cases (7-day token expiry in Testing mode, service-account access, quotas, Windows and WSL notes): docs/troubleshooting.md.

Development

npm install
npm run typecheck && npm run lint && npm test   # no network needed
npm run build                                    # single-file dist via tsup

Tests fake the Search Console REST layer; nothing in CI talks to Google. See CONTRIBUTING.md.

License

MIT. Built by the maker of Searcherries.