MCP Gsc

mcp-gsc

Google Search Console MCP server — query search analytics, inspect URLs, manage sitemaps & more via natural language.

Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.

---

Quick Start

1. Get Credentials

You need OAuth client credentials from Google Cloud Console.

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Enable the Google Search Console API:

• APIs & Services → Library → search "Google Search Console API" → Enable

1. Configure OAuth consent screen (if not done):

• APIs & Services → OAuth consent screen → External
• Fill in app name + your email, add scope https://www.googleapis.com/auth/webmasters

1. Create credentials:

• APIs & Services → Credentials → Create Credentials → OAuth client ID
• Application type: Desktop app (allows localhost redirects automatically)
• Download the JSON file

1. Set the credentials path:

export GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json

1. Run setup to authorize:

npx mcp-gsc setup

This opens your browser for OAuth consent, saves a refresh token, verifies access to your GSC properties, and prints config snippets for your MCP client.

2. Add to Claude Code

claude mcp add gsc --scope user --transport stdio \

-e GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json \ -- npx -y mcp-gsc@latest

That's it. Restart Claude Code and the tools are available.

Also works with bunx mcp-gsc@latest if you have Bun.

Requires Node 22+ when running via npx.

Claude Desktop / Cursor

Add to your claude_desktop_config.json:

{

"mcpServers": { "gsc": { "command": "npx", "args": ["-y", "mcp-gsc@latest"], "env": { "GOOGLE_GSC_CREDENTIALS_PATH": "/path/to/credentials.json" } } } }

Codex CLI

Add to ~/.codex/config.toml (TOML, not JSON):

[mcp_servers.gsc]

command = "npx" args = ["-y", "mcp-gsc@latest"] startup_timeout_sec = 30 env = { GOOGLE_GSC_CREDENTIALS_PATH = "/path/to/credentials.json" }

Codex defaults to a 10s startup timeout, which is often too short for a cold npx fetch. Bump startup_timeout_sec (30 is safe) or install the package globally (npm i -g mcp-gsc) and use command = "mcp-gsc" instead.

Service Account (alternative)

For server-to-server auth without browser-based OAuth:

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. In Google Search Console, add the service account email as a user for each property
4. Point GOOGLE_GSC_CREDENTIALS_PATH to the key file — auth type is auto-detected

Tools (25)

Core Tools (always available)

Sites

Search Analytics

Dimensions: query, page, country, device, date, searchAppearance, hour

Types: web, image, video, news, discover, googleNews

Note: searchAppearance cannot combine with query or page. hour requires data_state="hourly_all" (last 10 days only). Country codes are ISO 3166-1 alpha-3 (usa, gbr, deu).

Sitemaps

URL Inspection

Rate limits: 600/minute + 2,000/day per site (tracked automatically).

Export

Extended Tools (disabled by default)

Enable with GOOGLE_GSC_ENABLE_EXTENDED_TOOLS=true:

Reporting Suite

SEO Suite

Technical SEO Suite

Write Tools (disabled by default)

Enable with GOOGLE_GSC_ENABLE_WRITES=true:

Indexing API prerequisites. The last two use a different Google API to the

rest of this server, so they need three things the other tools don't:

1. Re-run `mcp-gsc setup` — credentials created before this feature lack

the auth/indexing scope. The tools say so explicitly if yours do.

2. Enable the Indexing API on your Google Cloud project —

console.cloud.google.com/apis/library/indexing.googleapis.com

3. Be a verified _owner_ of the property in Search Console. Full-user

access is not enough.

Google officially supports the Indexing API only for pages carrying

JobPosting or BroadcastEvent structured data, with a default quota of

200 URLs/day. It requests a crawl — it never guarantees indexing.

Configuration

Property resolution: You can pass bare domains like example.com — the server auto-resolves to sc-domain:example.com or https://example.com/ by matching against your verified properties.

Examples

Ask your AI assistant:

• "Show me my top 10 queries this month"
• "Find quick wins for example.com"
• "Which pages have declining traffic over the last 3 months?"
• "Check if these URLs are indexed: url1, url2, url3"
• "Compare this week's performance to last week"
• "Export all search analytics data to CSV for the last 28 days"
• "Run a weekly SEO report for my site"
• "Find keyword cannibalization issues"

Future Tool Ideas

• Content gap analysis (requires competitor data integration)
• Core Web Vitals integration (via PageSpeed Insights API)
• Multi-property comparison
• Search appearance deep analysis
• Integration with Google Analytics for conversion data
• Automated reporting schedules

Updates

Using `npx @latest` (recommended): You always get the latest version.

Using a binary: The server checks for new releases on startup and logs to stderr if outdated.

mcp-gsc --version

Development

Requires Bun.

git clone https://github.com/pijusz/mcp-gsc.git

cd mcp-gsc bun install bun test # tests bun run build # standalone binary bun run inspect # MCP Inspector bun run check # biome format + lint

License

MIT