# search-console-mcp

A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for
**Google Search Console**. Point it at a Search Console property and query your
search-performance data, sitemaps, and URL index status from any MCP client
(Claude Code, Claude Desktop, Cursor, …).

It exists to *read and analyze* Search Console data — nothing else. It cannot
add sites, submit sitemaps, request indexing, or change anything.

## Read-only by design

Read-only is enforced at three independent layers, so there is no single point
of failure:

1. **OAuth scope.** Credentials are always downscoped to
   `https://www.googleapis.com/auth/webmasters.readonly`. Google's API rejects
   any write call made with this scope — regardless of the signed-in account's
   role. If you mint your credentials with this scope (the helper below does),
   even a leaked credential file cannot modify your account.
2. **Tool surface.** The server only implements read methods. There is no code
   path that mutates Search Console.
3. **Network surface.** The only host contacted is `googleapis.com`, via
   Google's official client libraries. No telemetry, no third-party endpoints.

Dependencies are limited to the official `mcp`, `google-api-python-client`, and
`google-auth` packages.

## Tools

| Tool | What it returns |
|------|-----------------|
| `list_sites` | Properties the account can access, with permission level |
| `search_analytics` | Performance report: clicks, impressions, CTR, position, grouped by query / page / country / device / date / search appearance, with filters |
| `list_sitemaps` | Sitemaps submitted for a property |
| `get_sitemap` | Index status and errors for one sitemap |
| `inspect_url` | URL Inspection: index coverage, last crawl, canonical, mobile usability (tight per-property quota) |

## Setup

### 1. Enable the API

In a [Google Cloud](https://console.cloud.google.com) project, enable the
**Google Search Console API**.

### 2. Mint read-only credentials

Create an OAuth **Desktop app** client in that project and download its JSON.
Then:

```bash
pip install "search-console-mcp[auth]"   # provides google-auth-oauthlib

python scripts/mint_token.py \
    --client-secrets /path/to/oauth_client.json \
    --output /path/to/gsc-readonly-credentials.json
```

A browser opens — **sign in as the account that has access to the Search
Console properties you want to read.** Viewer / Restricted access is enough.
The output file is an authorized-user credential limited to the read-only scope.

> A service-account key also works (no minting step) — just set
> `GOOGLE_APPLICATION_CREDENTIALS` to it and add the service-account email as a
> user on each property. The OAuth path above is recommended for personal use.

### 3. Register the server

`uvx` runs it without an explicit install:

```json
{
  "mcpServers": {
    "search-console": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "search-console-mcp", "search-console-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/gsc-readonly-credentials.json"
      }
    }
  }
}
```

See [`.mcp.json.example`](.mcp.json.example). Restart your MCP client, and the
five tools above become available.

## Develop

```bash
uv sync
uv run search-console-mcp   # starts the stdio server
```

## License

MIT — see [LICENSE](LICENSE).