# Google Search Console MCP

[![npm](https://img.shields.io/npm/v/@eduardmur/gsc-mcp)](https://www.npmjs.com/package/@eduardmur/gsc-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An MCP server that gives Claude, Cursor, Codex and any other MCP client clean access to Google Search Console: search analytics, question-shaped queries, ranking opportunities, URL inspection and sitemaps.

It runs on your machine, talks to Google with your own credentials, and sends nothing anywhere else. No telemetry.

## Why this one

Every GSC MCP server wraps the same API. The differences are in the details that decide whether the model gets numbers it can trust:

- **Dates are resolved on the server.** Ask for `last_28_days` and the server computes the range in the property's timezone (America/Los_Angeles, the one Search Console itself uses). That removes both the UTC off-by-one and the dates models make up when asked about "last month".
- **Windows end where the data ends.** Search Console reports lag 2-3 days. Preset ranges snap to the newest date that has rows, so trends are not biased by trailing empty days. Opt out with `anchor=today`.
- **Fresh data by default.** Requests use `dataState=all`, matching the numbers you see in the Search Console UI. Use `data_state=final` for stable reporting.
- **Comparisons are computed server-side.** `compare=previous_period` or `same_period_last_year` (shifted 364 days so weekdays align) returns one merged table with `clicks_change`, `position_change` and `is_new` per row. The model never has to join two tables, a task LLMs are unreliable at.
- **Compact responses.** One text block of minified JSON per call, paginated with `limit`/`offset`/`has_more`, nothing sent twice. Long sessions keep their context for rows.
- **Question-shaped queries in 10 languages.** A dedicated tool finds searches phrased as questions (what/how/why/compare/…) via regex filters that run inside Search Console itself: English, Spanish, French, Portuguese, Russian, Arabic, Hindi, Bengali, Indonesian and Chinese.
- **Read-only by default.** Sitemap submit/delete exist but only work when you start the server with `--enable-writes`.
- **Errors that name the fix.** Every failure message says what to do next, and `gsc-mcp doctor` checks the whole chain end to end.

## Quick start

Requires Node.js 20+ and a one-time Google sign-in:

```bash
npx -y @eduardmur/gsc-mcp login   # guided setup, ~2 minutes
npx -y @eduardmur/gsc-mcp doctor  # verify everything works
```

`login` walks you through creating your own free Google OAuth client (you control the credentials; nothing is shared with anyone) and signs you in via your browser. Details and alternatives in [docs/auth-oauth.md](docs/auth-oauth.md), [docs/auth-service-account.md](docs/auth-service-account.md) and [docs/auth-adc.md](docs/auth-adc.md).

Then add the server to your client:

**Claude Code**

```bash
claude mcp add gsc -- npx -y @eduardmur/gsc-mcp
```

**Claude Desktop**: add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@eduardmur/gsc-mcp"]
    }
  }
}
```

**Cursor**: add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@eduardmur/gsc-mcp"]
    }
  }
}
```

**Codex CLI**

```bash
codex mcp add gsc -- npx -y @eduardmur/gsc-mcp
```

Now ask things like:

> Which queries gained and lost the most clicks this week on example.com?
>
> What questions do people ask that we rank for but never answer on a dedicated page?
>
> Find cannibalization on sc-domain:example.com and tell me which page should win each query.

## Tools

| Tool | What it returns |
|---|---|
| `list-properties` | Properties the account can read, with permission levels. Start here. |
| `query` | Search analytics rows: dimensions (query, page, country, device, date, searchAppearance), Search-Console-side filters (contains/regex/country/device), metric filters, sorting, pagination up to 25k rows, optional compare with ready-made deltas. |
| `question-queries` | Searches phrased as questions, detected inside Search Console in 10 languages. The raw material for FAQ content, and the same questions people ask AI assistants. |
| `opportunities` | Four analyses over the top 5000 rows: `low_ctr` (impressions without clicks, adaptive threshold), `striking_distance` (positions 4-15), `long_tail` (4+ word queries), `cannibalization` (pages competing for one query). |
| `inspect-url` | Index status per URL: verdict, coverage, canonical chosen by Google vs declared (mismatches flagged), robots state, last crawl, rich results. Single URL or batches up to 20. |
| `sitemaps` | Submitted sitemaps with status, errors and counts. Submit/delete only with `--enable-writes`. |

Full parameter reference: [docs/tools.md](docs/tools.md).

## Prompts

Six ready-made recipes ship with the server and appear as slash commands in clients that support MCP prompts (in Claude Code: `/gsc:weekly-report` etc.):

`weekly-report` · `content-decay` · `striking-distance` · `cannibalization-check` · `questions-to-content` · `indexing-triage`

Each one is a step-by-step plan: which tools to call with which arguments, and what to deliver.

## CLI

```
gsc-mcp             # serve MCP on stdio (what your client runs)
gsc-mcp login       # connect a Google account (guided)
gsc-mcp logout      # remove saved tokens
gsc-mcp doctor      # 6 end-to-end checks: node, credentials, token, properties, query, freshness
```

Flags: `--enable-writes`, `--key-file <path>`, `--client <path>`, `--no-open`.

Tokens are stored in `~/.config/gsc-mcp/tokens.json` (0600). The only Google scope requested is `webmasters.readonly`.

## Prefer a hosted setup?

If you'd rather skip local setup, or want AI-visibility data next to your Search Console numbers (how ChatGPT, Perplexity, Gemini and AI Overviews talk about your brand), [Searcherries](https://searcherries.com) runs a hosted MCP with one-click OAuth: GSC, Bing Webmaster Tools, GA4 AI traffic and tracked AI answers in one server. The two are independent: neither needs the other. See [docs/hosted.md](docs/hosted.md).

## Troubleshooting

Run `gsc-mcp doctor` first; it pinpoints the failing step. Common cases (7-day token expiry in Testing mode, service-account access, quotas, Windows and WSL notes): [docs/troubleshooting.md](docs/troubleshooting.md).

## Development

```bash
npm install
npm run typecheck && npm run lint && npm test   # no network needed
npm run build                                    # single-file dist via tsup
```

Tests fake the Search Console REST layer; nothing in CI talks to Google. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE). Built by the maker of [Searcherries](https://searcherries.com).