io.github.sudomichael/search-console-mcp

Official

by sudomichael · TypeScript

Google Search Console for any MCP client - 30-second login, no Google Cloud project. Read-only.

Read-only Google Search Console access with 30-second login and no Google Cloud setup required.

Topics

claudecursorgoogle-search-consolemcpmodel-context-protocolseo

README.md8 KBView on GitHub

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. No API keys. Tokens never leave your machine.

Docs · npm · Report an issue

</div>

code

 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:

bash

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 to expect on first run

code

$ npx search-console-mcp-server login
Opening your browser to sign in with Google…

Connected. Your Search Console is ready — tokens stored in
~/.search-console-mcp (this machine only).

That's the whole setup. No clone, no Google Cloud console, no JSON files.

What it feels like

code

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):

bash

npx search-console-mcp-server login

2. Add to your MCP client:

Claude Code:

bash

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

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

json

{
  "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):

json

{ "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.

Development

bash

git clone https://github.com/sudomichael/search-console-mcp
cd search-console-mcp && npm install
npm run dev      # run from source
npm run build    # bundle to dist/ (10KB, no googleapis dependency)

The entire auth path is ~200 lines in src/auth.ts. To verify any privacy claim above, read the source.

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.

Install

claude_desktop_config.json

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