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

 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.

What to expect on first run

$ 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.

Related MCP server: gsc-mcp

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:

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

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.

Development

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.