<!-- The MCP Registry reads this marker out of the PyPI description to prove the package and the registry entry have the same owner. It must match `name` in server.json exactly, and it must survive any README rewrite. mcp-name: io.github.Mrshahidali420/gsc-indexer-mcp -->

Google Search Console MCP Server

An MCP server that gives Claude and other AI agents real control over Google Search Console — list your properties, check whether a URL is indexed, find the pages Google left out, run URL inspection in bulk, submit sitemaps, request indexing, and pull search analytics, all from a conversation.

Built for SEO practitioners tired of checking index status and submitting sitemaps by hand, one property at a time, and for the AI agents that can do it for them.

shahidali.co/tools/gsc-mcp is the project page: the same install lines, the tool list, and what the quota rules actually are, written for people who have not opened this repo.

<details> <summary><b>Contents</b></summary>

• Add it to your agent — one-liners for Claude Code, Cursor, VS Code, LM Studio
• Project status — what is verified, and on how many platforms
• Tools — the fifteen tools this server registers
• Why quota accounting is the hard part
• Finding what is not indexed · Reason codes
• Submitting URLs · Which tool · Before your first submission
• Requirements
• Install · The OAuth client is handled for you · Using your own OAuth client instead
• Getting started — first run, sign-in, the browser extension
• Development · Architecture
• Privacy — what leaves your machine, and what does not
• Known gaps — read this before trusting it with a client property
• Contributing · License

</details>

Add it to your agent

Claude Code, in one command:

claude mcp add gsc -- uvx gsc-indexer-mcp

Anything else that speaks MCP, by hand — this is the whole config:

{
  "mcpServers": {
    "gsc": { "command": "uvx", "args": ["gsc-indexer-mcp"] }
  }
}

uvx fetches and runs the published package with nothing installed first, which is why every button above is a one-liner. A .mcp.json with exactly that content sits in this repo, so cloning it is also enough.

No API key goes in any of these. Sign-in happens once, in your browser, when you first call gsc_setup() — see The OAuth client is handled for you.

---

Project status

Beta. The whole surface is wired up, and it has now met a real Google account — on one operating system, driven by one person.

0.1.0 drops the pre-release suffix so that pip install finds it without --pre. That is a decision about reach, not a claim of maturity: this project needs bug reports from people who are not its author, and a package pip refuses to install by default does not get them. Read the Known issues in CHANGELOG.md before pointing it at a property you care about — in particular, a transient rate-limit from Google currently ends the whole batch. Bug reports are the point; please file them.

Fifteen tools are registered on the server and covered by a wire-level smoke test that connects a real MCP client session and confirms every tool answers with a description. Storage, quota accounting, OAuth, and config are the foundation underneath them. Sign-in has been walked for real, on Windows against a live Google account — see docs/manual-smoke.md, which is also where the defects that run found are recorded. Submission has since driven a real browser and had Google confirm real Request Indexing calls, in Chrome and in Brave, against live properties. That is one platform and one operator, and every automated assertion about it is still made against a fake; see Known gaps for what that does and does not buy you.

| Milestone | Scope | State | |---|---|---| | 1. Foundation | Paths, logging, SQLite store, quota engine, OAuth + PKCE, config | Done | | 2. MCP surface | The tools below, exposed over MCP | Done | | 3A. Onboarding | Guided sign-in, browser/profile detection, the bridge extension | Done | | 3B. Submission | Browser-driven Request Indexing, job control | Verified live on Windows | | 4. Reporting | Indexation discovery and audits | Verified live on Windows |

Released versions and what changed in them are in CHANGELOG.md. Watch or star the repo if you want to know when the milestones above are verified on a platform other than Windows.

Tools

Shipped and registered on the MCP server today:

| Tool | What it does | |---|---| | gsc_list_sites | List every Search Console property the account can reach | | gsc_doctor | Diagnose auth, config and environment problems | | gsc_check_status | Index status for one or more URLs via the URL Inspection API (read-only, spends no Request-Indexing slot) | | gsc_quota | Request-Indexing and URL Inspection budget remaining today, per property | | gsc_performance | Clicks, impressions, CTR and position from Search Analytics | | gsc_submit_sitemaps | Submit or resubmit sitemaps to a property | | gsc_setup | Walk through sign-in and setup; idempotent, returns the single next step | | gsc_detect_browsers | Locate installed browsers and profiles for browser-driven submission | | gsc_use_browser | Pin the browser profile to drive, overriding the detector's recommendation | | gsc_request_indexing | Submit up to five URLs for indexing, one at a time. Blocks for minutes — see Submitting URLs | | gsc_start_indexing_job | Queue a background submission run over any number of URLs; returns at once | | gsc_job_status | Progress and state for one submission job, or the most recent | | gsc_stop_job | Ask a running submission job to stop after the URL in flight | | gsc_find_unindexed | Find which of a property's URLs are not indexed, and why — see Finding what is not indexed | | gsc_audit | The current indexation position for a property, read from the local store; spends no quota |

Why quota accounting is the hard part

Most tools in this space get Google's limits wrong, then get throttled and blame detection. Both limits that matter are per property, not per account:

| Limit | Value | Mechanic | |---|---|---| | Request Indexing | ~11 slots per property | Rolling — each slot frees 24h + 1 min after its own use | | URL Inspection | 2,000 per day per property | Daily reset | | URL Inspection | 600 per minute per property | Rate limit |

Properties are independent, so eight properties means eight independent budgets. This server tracks slots individually rather than counting a daily total, so it knows the exact minute the next slot opens — and it deliberately over-counts rather than under-counts when a race is possible, because a short wait is cheaper than a hard Quota Exceeded.

Finding what is not indexed

gsc_find_unindexed collects candidate URLs — from the property's registered sitemaps, from URLs already in the local store, or both — inspects the ones whose last inspection has gone stale, and reports each unindexed URL with a reason. limit caps how many URLs are inspected, not how many come back: an inspection spends budget, and a cap that only trimmed the output would pay full price for an answer it discarded. Which URLs a capped run reaches follows the store's own URL ordering (alphabetical), not staleness, so a capped run is a sample rather than a worst-first sweep.

gsc_audit answers the same question from the store alone — no HTTP inspection, no budget spent. It is point-in-time: it reports what the last inspection found, and carries as_at and a stale count so you can tell how old that picture is. There are deliberately no movement numbers.

Reason codes

There are ten of them. submitting_helps on each row is the one to act on before calling gsc_request_indexing:

| Reason | submitting_helps | What it means | |---|---|---| | discovered-not-indexed | yes | Google knows the URL but has not crawled it | | unknown-to-google | yes | Google has never seen the URL | | crawled-not-indexed | yes | Google crawled it and chose not to index it — improve it, then submit | | 404 | no | The URL returns not-found | | redirect | no | The URL redirects elsewhere | | noindex | no | A noindex directive on the page or its response | | soft-404 | no | Returns 200 but reads as an error or empty page | | robots-blocked | no | robots.txt blocks the URL | | duplicate | no | Google chose a different canonical | | alt-canonical | no | An alternate page pointing at its own canonical — no action |

If you have read the eight-code list in the design notes and counted ten here, the extra two are discovered-not-indexed and unknown-to-google, kept separate from crawled-not-indexed on purpose. All three answer yes to "can a quota slot move this", but not to "what do I do first", and that is the part you act on. Discovered and unknown are pages Google has not judged — it has not fetched them yet, so submitting is the whole remedy. Crawled-not-indexed is a page it fetched and passed on; a fresh crawl can reverse that verdict, but resubmitting byte-identical content re-crawls to the same one. Improve the page, then submit it.

Slots are roughly eleven per property per rolling day and unrecoverable, and crawled-not-indexed is usually the biggest bucket on a real site. submitting_helps: true means the slot can work, not that today is the day to spend it.

A URL whose state could not be established — a failed inspection, or a result a re-check could not confirm — is reported as undetermined, never as unindexed. Absence of evidence is not a finding.

Submitting URLs

Google has no API for Request Indexing that a tool like this can use, so submission goes through your own browser: the bridge extension, loaded into the profile you paired during gsc_setup, clicks Request Indexing in a real Search Console session. That has three consequences worth knowing before you spend anything.

It is slow, and the slowness is the feature. Submissions are pace