# gsc-mcp

A free, open-source [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude (or any other MCP client -- ChatGPT, Codex, Cursor) direct, read-only access to your Google Search Console data: search analytics (clicks/impressions/CTR/position), sitemap status, and URL inspection.

Built by [GrowthLever](https://growthlever.app) because, as a marketer, I don't love the interface for Google's products -- Search Console, GA4, and Ads included. This lets me put my own translation layer on top of the raw data and ask Claude for the insight directly, instead of digging through Google's UI. It's free because the tool isn't the product -- the workflows I run on top of it are (see the bottom of this page).

## Bring your own Google credentials

This runs entirely on **your** machine using a Google OAuth client **you** create in your own Google Cloud account. Your refresh token never leaves your disk, and no Search Console data ever passes through a server GrowthLever operates. There's no account to create with us, nothing to sign up for, nothing to trust us with. See [SECURITY.md](SECURITY.md) and [PRIVACY.md](PRIVACY.md) for the full detail.

## What it exposes

Four read-only tools:

| Tool | What it does |
|---|---|
| `list_sites` | Lists the GSC properties the authorized account can access |
| `search_analytics` | Clicks/impressions/CTR/position, filterable by query, page, country, device, date |
| `list_sitemaps` | Submitted sitemaps and their status/errors |
| `inspect_url` | Index coverage, canonical URL, and crawl details for one URL |

Nothing here can change Search Console settings or submit/delete anything -- every call is a `GET` or a read-only `query`/`inspect` request.

## Get started

**[QUICKSTART.md](QUICKSTART.md)** -- 10-minute setup, most of it waiting on Google's console. Short version:

```bash
npx -y @growthlever/gsc-mcp auth --credentials ~/Downloads/client_secret.json
npx -y @growthlever/gsc-mcp doctor
```

Then point your Claude config at `npx -y @growthlever/gsc-mcp` (example in [examples/claude-desktop-config.json](examples/claude-desktop-config.json)) and ask it something -- see [PROMPTS.md](PROMPTS.md) for a starter pack, split by founder-building-from-zero and scale-up-optimizing-what-works.

Something not working? Run `gsc-mcp doctor` first, then check [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

## Local development

```bash
npm install
node bin/gsc-mcp.js auth --credentials <path to client_secret.json>
node bin/gsc-mcp.js doctor
node bin/gsc-mcp.js            # runs the MCP server over stdio
node test/smoke.js             # spawns the server and verifies tool registration
```

## Docs

- [QUICKSTART.md](QUICKSTART.md) -- setup, start to finish
- [PROMPTS.md](PROMPTS.md) -- starter prompt pack
- [SECURITY.md](SECURITY.md) -- what this touches, what it can't do, how to revoke access
- [PRIVACY.md](PRIVACY.md) -- what's collected (nothing) and who sees your data
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) -- plain-language fixes for common Google/OAuth errors
- [examples/](examples/) -- config for Claude Desktop and Codex CLI, plus a weekly-review prompt template

## Why this is free

I'm a fractional Head of Growth -- most of the founders and operators I talk to are starting from scratch and didn't get into business to learn marketing. The best early move is almost always laying an organic foundation while referrals and word of mouth do the rest, because there isn't budget for paid yet. Scale-ups have a different problem: figuring out which pages and content are actually working so they can double down instead of guessing.

Either way, the blocker usually isn't access to data -- Search Console is free -- it's translating that data into "what do I do next." That's what this tool plus a decent prompt does. I'm giving the tool away because the tool isn't hard to build; the judgment about what to do with the output is where the actual value is, and that's what I write about and go deeper on for subscribers.

If you want the applied layer -- prompt packs by use case, weekly review and client-reporting templates, and the founder/scale-up workflows this is built around -- that's on [Substack](https://growthlever.substack.com) (subscriber content).

## License

[MIT](LICENSE.md). Fork it, self-host it, build on it.