mcp-seo-audit
A Model Context Protocol (MCP) server for SEO auditing, Google Search Console analytics, URL indexing, Core Web Vitals, and site analysis. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
Forked from AminForou/mcp-gsc and rewritten with 23 tools, bug fixes, and a full test suite.
What It Does
| Category | Tools | Description |
|---|---|---|
| Property Management | list_properties, add_site, delete_site | List, add, and remove GSC properties |
| Search Analytics | get_search_analytics, get_advanced_search_analytics, get_performance_overview, get_search_by_page_query, compare_search_periods | Query clicks, impressions, CTR, position with filtering, dimensions, and period comparison |
| URL Inspection | inspect_url, batch_inspect_urls | Check indexing status, crawl info, canonical, robots for one or many URLs |
| Indexing API | request_indexing, request_removal, check_indexing_notification, batch_request_indexing | Submit/remove URLs from Google's index via the Indexing API |
| Sitemaps | get_sitemaps, submit_sitemap, delete_sitemap | List, submit, and delete sitemaps |
| Core Web Vitals | get_core_web_vitals | LCP, FID, CLS, INP, TTFB via the Chrome UX Report (CrUX) API |
| SEO Analysis | find_striking_distance_keywords, detect_cannibalization, split_branded_queries | Find keywords at positions 5-20, detect pages competing for the same query, split branded vs non-branded traffic |
| Site Audit | site_audit | All-in-one report: sitemap health, indexing status, canonical mismatches, performance summary |
| Auth | reauthenticate | Switch Google accounts by clearing cached OAuth tokens |
23 tools total.
Setup
1. Google API Credentials
OAuth (recommended)
- Go to Google Cloud Console
- Enable the Search Console API and Web Search Indexing API
- Create an OAuth 2.0 Client ID (Desktop app)
- Download
client_secrets.json
Service Account
- Create a service account in Google Cloud Console
- Download the JSON key file
- Add the service account email to your GSC properties
2. Install
git clone https://github.com/GiorgiKemo/mcp-gsc.git
cd mcp-gsc
python -m venv .venv
# Activate:
# macOS/Linux: source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -r requirements.txt
3. Configure Your MCP Client
Claude Code (~/.claude/settings.json)
{
"mcpServers": {
"seo-audit": {
"command": "/path/to/mcp-gsc/.venv/bin/python",
"args": ["/path/to/mcp-gsc/gsc_server.py"],
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json"
}
}
}
}
Claude Desktop (claude_desktop_config.json)
Same JSON structure — see Claude Desktop MCP docs for config file location.
4. Optional: CrUX API Key
For Core Web Vitals data, set CRUX_API_KEY in the env block:
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json",
"CRUX_API_KEY": "your-google-api-key"
}
Get one from Google AI Studio or the Cloud Console with CrUX API enabled.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
GSC_OAUTH_CLIENT_SECRETS_FILE | OAuth | client_secrets.json | Path to OAuth client secrets |
GSC_CREDENTIALS_PATH | Service account | service_account_credentials.json | Path to service account key |
GSC_SKIP_OAUTH | No | false | Set to true to skip OAuth and use service account only |
GSC_DATA_STATE | No | all | all = fresh data matching GSC dashboard, final = confirmed data (2-3 day lag) |
CRUX_API_KEY | No | — | Google API key for Core Web Vitals (CrUX) |
Example Prompts
"List my GSC properties"
"Show search analytics for cdljobscenter.com last 28 days"
"Find striking distance keywords for my site"
"Detect keyword cannibalization"
"Run a full site audit"
"Check Core Web Vitals for cdljobscenter.com"
"Inspect indexing status of these URLs: /jobs, /companies, /pricing"
"Request indexing for https://mysite.com/new-page"
"Compare search performance this month vs last month"
Tests
71 tests covering all 23 tools with mocked Google API calls:
# Activate venv first
python -m pytest test_gsc_server.py -v
What Changed From the Original
- 23 tools (up from ~10) — added Indexing API, CrUX, SEO analysis, site audit
- 7 bug fixes — sort direction mapping, origin/URL detection, empty rows crash, API key leak, blocking sleep, service caching, stale cache on reauth
- 71-test QA suite — full coverage with mocked API calls
- Security — API keys redacted from error messages
- Performance — Google API service objects cached, async sleep instead of blocking
License
MIT. See LICENSE.
Based on AminForou/mcp-gsc.