Show HN: Google Search Console MCP

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

2 Commits

2 Commits

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

cli.mjs

cli.mjs

gsc.mjs

gsc.mjs

mcp.mjs

mcp.mjs

package-lock.json

package-lock.json

package.json

package.json

Repository files navigation

Give your AI assistant read access to your Google Search Console data — across every property you own.

Bug report · Feature request · More projects

Checking how a site is doing on Google usually means logging into Search Console, picking a property, fiddling with date ranges, and eyeballing charts. This connects your assistant (Claude Code, Claude Desktop, Cursor, or any MCP client) straight to the Search Console API, so you can just ask — "what are my top queries this month?" or "is this page indexed yet?" — and get the numbers back in seconds.

One service-account credential covers all your properties at once, so you can ask across sites without switching accounts. And because the credential is read-only, your assistant can look but never touch.

✨ What it does and does not do

It does:

List every Search Console property the credential can read.

Pull clicks, impressions, CTR, and average position — grouped by query, page, date, country, device, or search appearance.

Check the index status of any URL (indexed or not, last crawl, canonical, coverage state, mobile usability).

Show your submitted sitemaps and their indexed-vs-submitted counts.

It does not:

Write anything. The credential uses Google's read-only Search Console scope, so it cannot submit sitemaps, change settings, add or remove properties, or modify your account in any way.

Bypass Search Console's own data limits. It sees exactly what the API exposes — the same ~16-month window and sampling Google gives everyone.

Send your data anywhere except between your machine and Google's API. There is no third-party server in the middle.

📦 Before you start

You need:

A Google Cloud project and the gcloud CLI (or the Cloud Console) to create a service account.

One or more verified Google Search Console properties you can grant access on.

Node.js 22.5 or newer.

An MCP-capable assistant (for example Claude Code).

🔑 Get a credential

The server authenticates as a service account — a robot Google identity with its own email. You create it once, grant it read access on each property, and it can then read all of them.

1. Create the service account and key

gcloud config set project YOUR_PROJECT_ID gcloud services enable searchconsole.googleapis.com gcloud iam service-accounts create gsc-reader --display-name="GSC Reader"

mkdir -p ~/.config/gsc-mcp gcloud iam service-accounts keys create ~/.config/gsc-mcp/key.json \ --iam-account=gsc-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com

That writes a JSON key to ~/.config/gsc-mcp/key.json. Keep it private — it is a credential, not config. (This repo's .gitignore already blocks *key*.json so you can't commit it by accident.)

The service account lives in one Cloud project, but its identity works for any property you grant it on — the project choice does not matter.

1. Grant it on each property

In Search Console, open each property → Settings → Users and permissions → Add user. Add the service-account email (gsc-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com) with the Restricted (read) role.

Adding a new site later is just one more grant here — no code or config changes.

🚀 Install

git clone https://github.com/AkashRajpurohit/gsc-mcp.git cd gsc-mcp npm install

Then register it with your assistant. Note the full path to mcp.mjs — you will need it below:

echo "$PWD/mcp.mjs"

Claude Code

claude mcp add gsc --scope user -- node "$PWD/mcp.mjs"

--scope user registers it for every Claude Code session on the machine. Restart the session (or start a new one) to pick up the tools.

Claude Desktop

Open Settings → Developer → Edit Config (or edit claude_desktop_config.json directly) and add:

{ "mcpServers": { "gsc": { "command": "node", "args": ["/absolute/path/to/gsc-mcp/mcp.mjs"] } } }

Restart Claude Desktop.

Cursor

Open Settings → MCP → Add new global MCP server (or edit ~/.cursor/mcp.json) and add the same gsc entry as above:

{ "mcpServers": { "gsc": { "command": "node", "args": ["/absolute/path/to/gsc-mcp/mcp.mjs"] } } }

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json and add the same gsc entry under mcpServers.

VS Code (GitHub Copilot)

Add it to .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette):

{ "servers": { "gsc": { "command": "node", "args": ["/absolute/path/to/gsc-mcp/mcp.mjs"] } } }

If your key is not at the default path, add "env": { "GSC_KEY_PATH": "/absolute/path/to/key.json" } to any of the entries above.

Any other MCP client

Register a stdio server that runs node /absolute/path/to/gsc-mcp/mcp.mjs. That is all the server needs.

Once registered, start a new session and ask your assistant to "list my Search Console sites." If it comes back with your properties, you are ready.

💬 How to use it

Just talk to your assistant. For example:

"List all my Search Console properties."

"What are my top 20 queries for example.com over the last 28 days?"

"Show me the pages losing clicks this month compared to last."

"Which queries have high impressions but a low CTR?"

"Is https://example.com/blog/my-post/ indexed by Google?"

"How many URLs did my sitemap submit vs get indexed?"

Behind the scenes it offers four tools your assistant uses automatically:

Tool What it does

gsc_list_sites Lists readable properties and their exact siteUrl values.

gsc_search_analytics Clicks, impressions, CTR, and position grouped by query, page, date, country, device, or search appearance.

gsc_inspect_url Index status of a single URL (indexed, last crawl, canonical, coverage).

gsc_list_sitemaps Submitted vs indexed counts per sitemap, with errors and warnings.

Every tool is read-only — the underlying credential physically cannot change anything in your account.

🧪 Try it without an assistant

There's a small CLI wrapping the same core, handy for a sanity check:

node cli.mjs sites node cli.mjs perf "sc-domain:example.com" node cli.mjs pages "sc-domain:example.com" node cli.mjs queries "sc-domain:example.com" node cli.mjs inspect "sc-domain:example.com" "https://example.com/blog/my-post/" node cli.mjs sitemaps "sc-domain:example.com"

Domain properties look like sc-domain:example.com; URL-prefix properties look like https://example.com/. Run node cli.mjs sites first to see the exact siteUrl for each of your properties.

⚙️ Configuration

Variable Default Description

GSC_KEY_PATH ~/.config/gsc-mcp/key.json Path to the service-account JSON key.

🏗️ How it fits together

MCP client ──stdio──▶ mcp.mjs ──▶ gsc.mjs ──▶ Google Search Console API (tools) (auth + calls) (service-account key)

gsc.mjs — the Google API client. Authenticates with the service-account key and wraps the Search Console API (sites, search analytics, URL inspection, sitemaps).

mcp.mjs — the MCP server (stdio transport) that exposes those tools to your assistant.

cli.mjs — the same core, runnable by hand.

The core (gsc.mjs) is transport-agnostic. To run this as an always-on remote MCP instead of a local stdio process, containerize it, expose it over HTTP/SSE behind an authenticating proxy, mount the key as a secret, and register the remote URL with your client — only the hosting changes.

🩺 If it can't find your sites

gsc_list_sites returns an empty list — the service account isn't granted on any property yet. Re-check step 2: the email you added in Search Console must match your key's client_email exactly.

Auth or "file not found" errors — the key isn't where the server expects it. Confirm the path, or set GSC_KEY_PATH to point at it.

A specific property 403s — that one property hasn't been shared with the service account. Add it under Users and permissions.

⚖️ Licensing and disclaimer

This project is not affiliated with, endorsed by, or associated with Google in any way. It is an independent, open-source tool that talks to Google's public Search Console API using credentials you create and control. "Google Search Console" is a trademark of Google LLC and is used here only to describe what the tool works with.

The tool is released under the MIT license (see LICENSE). It is provided as-is, with no warranty. It only ever uses Google's read-only Search Console scope, so it can read your data but never modify your account.

About

Give your AI assistant read access to your Google Search Console data

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

JavaScript 100.0%