mcp-seo-audit

A Model Context Protocol (MCP) server for SEO auditing with Google Search Console, Indexing API, Chrome UX Report, PageSpeed Insights, local Lighthouse, robots.txt checks, sitemap analysis, on-page SEO inspection, crawl audits, and live site analysis. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Forked from AminForou/mcp-gsc and expanded into a broader technical SEO and performance audit server with 30 tools and a full test suite.

What It Does

30 tools total.

Setup

1. Google API Credentials

OAuth (recommended)

1. Go to Google Cloud Console

2. Enable the Search Console API and Web Search Indexing API

3. Create an OAuth 2.0 Client ID (Desktop app)

4. Download `client_secrets.json`

Service Account

1. Create a service account in Google Cloud Console

2. Download the JSON key file

3. Add the service account email to your GSC properties

2. Install

Option A: PyPI

MCP clients can run the PyPI package directly:

uvx mcp-seo-audit

Or install it as a persistent command:

pipx install mcp-seo-audit

Option B: Source checkout

git clone https://github.com/GiorgiKemo/mcp-seo-audit.git
cd mcp-seo-audit
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`)

With the PyPI package:

{
  "mcpServers": {
    "seo-audit": {
      "command": "uvx",
      "args": ["mcp-seo-audit"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json",
        "PAGESPEED_API_KEY": "your-google-api-key",
        "CRUX_API_KEY": "your-google-api-key"
      }
    }
  }
}

With a source checkout:

{
  "mcpServers": {
    "seo-audit": {
      "command": "/path/to/mcp-seo-audit/.venv/bin/python",
      "args": ["/path/to/mcp-seo-audit/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json",
        "PAGESPEED_API_KEY": "your-google-api-key",
        "CRUX_API_KEY": "your-google-api-key"
      }
    }
  }
}

Claude Desktop (`claude_desktop_config.json`)

Same JSON structure — see Claude Desktop MCP docs for config file location.

4. Optional: Performance API Keys

For field and lab performance data, set `CRUX_API_KEY` and `PAGESPEED_API_KEY` in the env block:

"env": {
  "GSC_OAUTH_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json",
  "CRUX_API_KEY": "your-google-api-key",
  "PAGESPEED_API_KEY": "your-google-api-key"
}

You can also set `GOOGLE_API_KEY`; the server uses it as the PageSpeed Insights fallback key.

Environment Variables

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"
"Run PageSpeed Insights for https://example.com"
"Run a local Lighthouse audit for https://example.com"
"Inspect robots.txt for https://example.com"
"Analyze https://example.com/sitemap.xml"
"Analyze on-page SEO for https://example.com/jobs"
"Crawl https://example.com and report duplicate titles"
"Run a live SEO audit for https://example.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

96 tests covering all 30 tools with mocked Google/API/web-audit calls:

# Activate venv first
python -m pytest test_gsc_server.py -v

What Changed From the Original

• 30 tools — added PSI, local Lighthouse, robots.txt inspection, sitemap validation, page SEO analysis, crawl audits, and live site audits
• Robustness fixes — OAuth scope alignment, sort direction mapping, origin/URL detection, sitemap BOM and plain-text handling, external redirect crawl guards, empty rows handling, API key redaction, service caching, and stale cache handling on reauth
• 96-test QA suite — coverage for GSC, CrUX, PSI, Lighthouse CLI, fallback behavior, robots, sitemaps, crawl audits, safety gates, auth scopes, and live-audit composition
• Security — private/local network fetches blocked by default, mutating Google tools gated behind an explicit env flag, and API keys redacted from error messages
• Performance — Google API service objects cached, async sleep instead of blocking, async CrUX HTTP calls, PSI-to-Lighthouse fallback, plus lab-performance tooling on top of CrUX field data
• Audit quality — local-preview aware canonical warnings, visible-content parsing that ignores `noscript` duplicates, severity-ranked SEO findings, image alt audits, crawlable-link checks, invalid JSON-LD detection, viewport/lang checks, and stricter canonical/robots diagnostics

License

MIT. See LICENSE.

Based on AminForou/mcp-gsc.