gsc-mcp 0.1.0

MCP server for Google Search Console. Query search analytics, inspect URLs, and monitor SEO performance from any MCP-compatible client.

gsc-mcp

Google Search Console as MCP tools — query search analytics, inspect URLs, and monitor SEO performance from any MCP-compatible AI client (Claude Desktop, Claude Code, Claude.ai, Gemini CLI, Cursor, etc.).

Zero vendor middleware. Zero ongoing cost. Each user authenticates with their own Google account against Google's free Search Console API.

---

Why this exists

Pulling GSC data into an AI client normally means either (a) manual CSV exports, (b) a paid data-pipeline vendor like Windsor or Coupler, or (c) building your own script and glue. This is option (d): a small, self-contained MCP server you install once and use from anywhere. Pairs naturally with Google's Analytics MCP for a complete SEO + user behavior picture.

---

Tools

All tools are read-only. No writes in v1.

Tool	What it does
gsc_list_sites	Enumerate every verified Search Console property for the authenticated user
gsc_query_search_analytics	Flexible analytics query — any combination of dimensions (query, page, country, device, date, searchAppearance) and filters
gsc_top_queries	Convenience: top N search queries for a site over a recent window
gsc_top_pages	Convenience: top N landing pages for a site over a recent window
gsc_inspect_url	URL inspection — indexing verdict, coverage state, Google-chosen canonical, last crawl, mobile usability, rich results
gsc_list_sitemaps	List registered sitemaps with status, errors, warnings, last submitted date
gsc_health_check	Auth + API reachability diagnostic (use this first when something breaks)

---

Setup

Three steps. ~15 minutes total.

1. Google Cloud — create an OAuth client

1. Open Google Cloud Console.
2. Create (or reuse) a project. Name it something like gsc-mcp.
3. Enable the Search Console API: one-click link.
4. Go to APIs & Services → Credentials.
5. If you haven't already, configure the OAuth consent screen:
   • User type: External.
   • App name: gsc-mcp, support email: your email, developer email: your email.
   • Add yourself as a Test user (under "Audience" / "Test users").
6. Click Create Credentials → OAuth client ID.
   • Application type: Desktop app.
   • Name: gsc-mcp-local.
7. Download JSON. Move the downloaded file to:

   ~/.config/gsc-mcp/credentials.json
   

   (Create the directory if it doesn't exist: mkdir -p ~/.config/gsc-mcp)

2. Install the server

# From this repository:
pip install --user .

# Or, once published to PyPI:
pipx install gsc-mcp

This installs the gsc-mcp console command and the gsc_mcp Python module.

3. Authenticate once

gsc-mcp auth

A browser window opens. Sign in with the Google account that owns your Search Console properties. You'll see a "Google hasn't verified this app" screen — that's expected because the app is for your personal use; click Advanced → Go to gsc-mcp (unsafe) and continue.

The token is saved to ~/.config/gsc-mcp/token.json (chmod 600) and refreshed automatically from here on.

Verify everything works:

gsc-mcp info
# gsc-mcp version: 0.1.0
# Credentials path: /Users/you/.config/gsc-mcp/credentials.json  (exists: True)
# Token path:       /Users/you/.config/gsc-mcp/token.json  (exists: True)

---

Connect it to a client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on Linux/Windows, and add:

{
  "mcpServers": {
    "gsc": {
      "command": "gsc-mcp"
    }
  }
}

Restart Claude Desktop. Type /mcp in a chat — you should see gsc listed with 7 tools.

Claude Code

claude mcp add gsc -- gsc-mcp

Or edit ~/.claude.json / the project .claude/mcp.json directly:

{
  "mcpServers": {
    "gsc": {
      "command": "gsc-mcp"
    }
  }
}

Claude.ai

1. Settings → Connectors → Add custom connector.
2. Name: GSC. Command: gsc-mcp.
3. Enable it.

Cursor, Windsurf, Gemini CLI, etc.

Any MCP-compatible client accepts the same stdio server config. Command: gsc-mcp. No args.

---

Example prompts once connected

What verified sites do I have in Search Console?

Show me the top 20 search queries for defusely.com over the last 30 days.

Which pages on defusely.app have the biggest impression-to-click gap?

Inspect https://defusely.com/pricing — is it indexed, what's the canonical, when
was it last crawled?

List all sitemaps registered for defusely.com and flag any with errors.

Compare CTR on mobile vs desktop for the top 10 queries on defusely.com this month.

---

Configuration

All paths are overrideable via environment variables:

Variable	Default	Purpose
GSC_MCP_CREDENTIALS	~/.config/gsc-mcp/credentials.json	OAuth client JSON from Google Cloud
GSC_MCP_TOKEN	~/.config/gsc-mcp/token.json	Cached access token (auto-managed)

---

Troubleshooting

Error 403 on every call — the Search Console API isn't enabled on your Google Cloud project, or the authenticated Google account doesn't own the property. Enable the API at the Search Console API library page and verify site ownership in Search Console.

Error 401 / token refresh fails — your refresh token was revoked (Google does this after ~6 months of non-use or on password change). Delete the token and re-auth:

rm ~/.config/gsc-mcp/token.json
gsc-mcp auth

Site not found — call gsc_list_sites first to see the exact siteUrl format. Domain properties use sc-domain:example.com; URL-prefix properties use https://example.com/ with the trailing slash.

URL inspection returns "quota exceeded" — the URL Inspection API is capped at ~2000 calls per property per day. Wait 24 hours or use bulk URL inspection sparingly.

Data looks stale — Search Console data typically lags real-time by 2-3 days. The default date range in this server ends 3 days ago for this reason. Don't query end_date = today and expect full data.

---

License

Apache 2.0 — see LICENSE.

Contributing

Issues and PRs welcome. This is deliberately small; keep changes focused on the GSC API surface.