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

4. 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

5. Create credentials:

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

6. Set the credentials path:

export GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json

7. 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:

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

| 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