google-search-console-mcp

<!-- 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, submit sitemaps, pull search analytics, and diagnose setup problems, all from a conversation.

[![PyPI](https://img.shields.io/pypi/v/gsc-indexer-mcp?label=pypi%20gsc-indexer-mcp&color=blue)](https://pypi.org/project/gsc-indexer-mcp/)
[![CI](https://github.com/Mrshahidali420/google-search-console-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mrshahidali420/google-search-console-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-green)](LICENSE)
[![Status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange)](#project-status)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)

> 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](https://www.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.

## Add it to your agent

[![Install in VS Code](https://img.shields.io/badge/VS_Code-install-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=gsc&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22gsc-indexer-mcp%22%5D%7D)
[![Install in Cursor](https://img.shields.io/badge/Cursor-install-000000?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=gsc&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJnc2MtaW5kZXhlci1tY3AiXX0%3D)
[![Install in LM Studio](https://img.shields.io/badge/LM_Studio-install-4A4A4A)](lmstudio://add_mcp?name=gsc&config=eyJuYW1lIjoiZ3NjIiwiY29tbWFuZCI6InV2eCIsImFyZ3MiOlsiZ3NjLWluZGV4ZXItbWNwIl19)

Claude Code, in one command:

```bash
claude mcp add gsc -- uvx gsc-indexer-mcp
```

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

```json
{
  "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`](.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](#the-oauth-client-is-handled-for-you).

---

## Project status

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

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](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](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](#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](#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 brow