search-console-mcp

Search Console was built for dashboards. This gives you a conversation instead.

Talk to your Google Search Console from Claude, Cursor, or any MCP client — one sign-in, 30 seconds, no Google Cloud project.

 Google Search Console
          │
          ▼
  search-console-mcp        ← runs on your machine, read-only
          │
          ▼
  Claude / Cursor / any MCP client
          │
          ▼
  "Why did my traffic drop?"

Every other Search Console MCP server makes you create a Google Cloud project, enable APIs, and wrangle service-account JSON. This one doesn't:

npx search-console-mcp-server login

Your browser opens, you sign in with Google, done. Tokens are minted by Google directly to your machine and stored only in ~/.search-console-mcp/ — nothing passes through anyone's servers.

| | This server | Typical GSC MCP setup | | --- | --- | --- | | Setup | npx … login, sign in, done (~30s) | Create a Google Cloud project, enable the API, create OAuth credentials, download JSON, point config at it | | Runtime | Node — npx, nothing to install | Python + uv/venv | | Can it modify your site data? | Impossible — read-only scope by construction | Write scopes with destructive ops "disabled by default" | | Analyses | 5 built-in (checkup, cannibalization, striking distance, traffic drop, indexing audit) | Bring your own prompts |

What it feels like

You:  Which of my pages are closest to page one?

Claude:  Three real opportunities, by impressions at stake:

  1. /pricing — "scoreboard app pricing" sits at position 11.2 with
     2,400 impressions/mo and almost no clicks. One position-group
     jump is worth ~90 clicks/mo. The title doesn't contain the
     query; start there.

  2. /templates/trivia — position 12.8 on "trivia scoreboard",
     1,100 impressions/mo. The page ranks but has no H2 matching
     the intent.

  3. /blog/keep-score-online — position 9.4, already page one on
     some days. It's cannibalizing with /features — run
     cannibalization_check before touching it.

(Illustrative output — shape and numbers are what the tools return from your real data.)

Built-in SEO analysts

Five ready-made analyses ship as MCP prompts — slash-commands in clients that support them. Outcomes, not API calls:

| Prompt | What you get | | --- | --- | | seo_checkup | Trend vs last month, biggest movers, and the top 3 moves worth making | | cannibalization_check | Queries where two of your pages compete — which should win, and how to fix it | | striking_distance | Queries sitting at position 5–15 — the fastest traffic you're not getting, with the fix per page | | traffic_drop | When the drop started, which pages/queries lost, indexed-or-not, most likely cause | | indexing_audit | Sitemap status + index inspection of your top pages, with plain-language fixes |

Setup

1. Sign in (one time):

npx search-console-mcp-server login

2. Add to your MCP client:

Claude Code:

claude mcp add gsc -- npx -y search-console-mcp-server

Claude Desktop / Cursor / anything else (mcpServers config):

{
  "mcpServers": {
    "gsc": { "command": "npx", "args": ["-y", "search-console-mcp-server"] }
  }
}

3. Ask:

• "Which of my pages lost the most clicks this month vs last?"
• "Show my queries sitting at position 8–15 with real impressions — what's closest to page 1?"
• "Is https://mysite.com/pricing indexed? If not, why?"
• "How much Google Discover traffic do I get?"

Tools

| Tool | What it does | | --- | --- | | list_properties | Your GSC properties (call first — gives exact siteUrl values) | | query_search_analytics | Clicks / impressions / CTR / position by query, page, date, country, device — filters, pagination, and every traffic source including Google Discover | | compare_periods | Biggest movers, computed for you: this period vs the prior one, per-page or per-query deltas, sorted by change | | inspect_url | Google's index status for a URL: indexed or not, why, chosen canonical, last crawl | | inspect_urls | The same, batched — up to 10 URLs in one call for indexing audits | | list_sitemaps | Submitted sitemaps with status |

Read-only by construction: the Google scope this tool requests (webmasters.readonly) cannot modify your properties, submit sitemaps, or change anything — not "disabled by default." Impossible.

What a compare_periods call hands your model (the model never does date arithmetic):

{ "key": "https://example.com/pricing",
  "current":  { "clicks": 1040, "impressions": 20502, "position": 6.4 },
  "previous": { "clicks": 1070, "impressions": 17176, "position": 5.8 },
  "deltaClicks": -30, "deltaImpressions": 3326, "deltaPosition": 0.6 }

Privacy

• Read-only Google scope (webmasters.readonly).
• Tokens live in ~/.search-console-mcp/credentials.json on your machine, chmod 600. npx search-console-mcp-server logout deletes them.
• No telemetry, no proxy — API calls go from your machine to Google, full stop.
• Prefer your own Google Cloud project? Set SEARCH_CONSOLE_MCP_CLIENT_ID / SEARCH_CONSOLE_MCP_CLIENT_SECRET and it uses yours.

FAQ / Troubleshooting

How can the login work without me creating Google credentials? The CLI ships a Google "Desktop app" OAuth client — the same supported model gcloud and GitHub's CLI use. Your tokens are still minted by Google directly to your machine (PKCE + localhost callback); they never touch our servers. The entire auth path is ~200 lines in src/auth.ts — read it. Want zero shared anything? Set SEARCH_CONSOLE_MCP_CLIENT_ID / SEARCH_CONSOLE_MCP_CLIENT_SECRET with your own credentials.

Switch Google accounts? npx search-console-mcp-server login again — Google shows the account picker.

"Not signed in" errors in my MCP client? Run the login from the same user account your client runs under; credentials live in ~/.search-console-mcp/.

A property is missing from list_properties. The signed-in Google account needs at least "Restricted" access to it in Search Console.

Why is yesterday missing from the data? Google Search Console data lags ~2–3 days. That's Google, not the tool. History goes back ~16 months.

Revoke access? npx search-console-mcp-server logout deletes local tokens; myaccount.google.com/permissions revokes the grant itself.

Looking for something proactive?

This MCP server helps you investigate — you ask, it answers.

After a week you may notice you keep asking the same questions: What dropped? What's closest to page one? What should I fix?

Percy is the other half: he checks your Search Console every week on his own, builds a strategy, emails you exactly what to change — then re-checks the live page and measures whether it worked.

Exploration here. Execution there. Same philosophy: real data, plain English, no dashboards.

MIT licensed. Issues and PRs welcome. Built by Percy.