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.

Go to Google Cloud Console
Create a project (or select existing)
Enable the Google Search Console API:
- APIs & Services → Library → search "Google Search Console API" → Enable
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
Create credentials:
- APIs & Services → Credentials → Create Credentials → OAuth client ID
- Application type: Desktop app (allows localhost redirects automatically)
- Download the JSON file
Set the credentials path:

export GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json

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 18+ 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"
      }
    }
  }
}

Service Account (alternative)

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

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

Tools (25)

Core Tools (always available)

Sites

Tool	Description
`list_properties`	List all GSC properties with permission levels
`get_property_details`	Verification info, ownership, permissions for a property

Search Analytics

Tool	Description
`search_analytics`	Query search performance (clicks, impressions, CTR, position) with dimensions, filters, and brand segmentation

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

Tool	Description
`list_sitemaps`	List sitemaps with status, type, indexed counts, errors
`get_sitemap`	Detailed sitemap info with content breakdown

URL Inspection

Tool	Description
`inspect_url`	URL indexing status, crawl info, rich results, canonicals
`batch_inspect_urls`	Inspect up to 10 URLs at once with categorized results

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

Export

Tool	Description
`export_csv`	Export full search analytics to CSV file (auto-paginates, up to 25K rows)

Extended Tools (disabled by default)

Enable with GOOGLE_GSC_ENABLE_EXTENDED_TOOLS=true:

Reporting Suite

Tool	Description
`performance_overview`	Aggregate metrics + daily trend breakdown
`compare_periods`	Compare two date ranges with delta calculations
`top_movers`	Biggest gains and drops between periods
`device_country_breakdown`	Performance by device and/or country

SEO Suite

Tool	Description
`quick_wins`	High-impression, low-CTR queries in striking distance (position 4-20)
`cannibalization`	Multiple pages competing for the same query
`opportunity_finder`	Emerging queries, growing impressions with low CTR, declining performers
`position_tracking`	Position changes over time for specific queries/pages
`ctr_anomalies`	Queries with abnormal CTR relative to position
`content_decay`	Pages/queries with impressions dropping >50% from historical peak
`weekly_seo_report`	All-in-one report: overview + quick wins + top movers

Technical SEO Suite

Tool	Description
`indexing_coverage`	Batch URL inspection with categorized indexing status
`sitemap_health`	Sitemap error patterns, freshness, indexed vs submitted ratio

Write Tools (disabled by default)

Enable with GOOGLE_GSC_ENABLE_WRITES=true:

Tool	Description
`add_site`	Add a new site to GSC
`delete_site`	Remove a site from GSC
`submit_sitemap`	Submit a new sitemap
`delete_sitemap`	Remove/unsubmit a sitemap

Configuration

Variable	Required	Default	Description
`GOOGLE_GSC_CREDENTIALS_PATH`	Yes	—	Path to OAuth client JSON or service account key
`GOOGLE_GSC_TOKEN_PATH`	No	Derived	Path to cached OAuth token (default: `*_token.json` next to credentials)
`GOOGLE_GSC_PROPERTY`	No	—	Default property URL (e.g., `sc-domain:example.com`). Accepts bare domains.
`GOOGLE_GSC_ENABLE_WRITES`	No	`false`	Enable write tools
`GOOGLE_GSC_ENABLE_EXTENDED_TOOLS`	No	`false`	Enable extended analytics tools (13 extra)
`GOOGLE_GSC_ENV_FILE`	No	`.env`	Path to .env file
`DEBUG`	No	—	Enable debug logging

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

mcp-gsc

Quick Install

mcp-gsc

Quick Start

1. Get Credentials

2. Add to Claude Code

Claude Desktop / Cursor

Service Account (alternative)

Tools (25)

Core Tools (always available)

Sites

Search Analytics

Sitemaps

URL Inspection

Export

Extended Tools (disabled by default)

Reporting Suite

SEO Suite

Technical SEO Suite

Write Tools (disabled by default)

Configuration

Examples

Future Tool Ideas

Updates

Development

License

Reviews