seo-mcp

Free, open-source MCP server for scanning websites for SEO issues — runs locally and integrates directly with Claude Desktop, Claude Code, Cursor, and other MCP clients.

No API keys required for core functionality. The conversation LLM performs AI analysis directly.

Features

• 28 SEO rules across meta, content, technical, and performance categories
• Multi-threaded scanning with worker_threads for parallel page analysis
• Site crawling with configurable depth, page limits, and robots.txt respect
• Deep page analysis — returns structured data for the conversation LLM to analyze (no API key needed)
• Real-time web monitoring via Firehose (Ahrefs) — track content changes with Lucene queries and SSE streaming
• Structured results with severity levels and actionable recommendations

Getting Started

Prerequisites

• Node.js >= 20.0.0
• An MCP client: Claude Desktop, Claude Code, Cursor, or any MCP-compatible client

Installation

git clone https://github.com/Stackwise-digital/seo-mcp.git
cd seo-mcp
npm install
npm run build

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "seo-mcp": {
      "command": "node",
      "args": ["/path/to/seo-mcp/dist/index.js"]
    }
  }
}

Claude Code

Add to your Claude Code MCP settings (~/.claude/.mcp.json):

{
  "mcpServers": {
    "seo-mcp": {
      "command": "node",
      "args": ["/path/to/seo-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "seo-mcp": {
      "command": "node",
      "args": ["/path/to/seo-mcp/dist/index.js"]
    }
  }
}

That's it — the 4 core SEO tools are ready to use. No API keys needed.

Enable Real-Time Monitoring (optional)

To use the Firehose real-time web monitoring tools:

1. Sign up at firehose.com (free during beta, no credit card)
2. Create a management key (starts with fhm_)
3. Add it to your MCP config:

{
  "mcpServers": {
    "seo-mcp": {
      "command": "node",
      "args": ["/path/to/seo-mcp/dist/index.js"],
      "env": {
        "FIREHOSE_MANAGEMENT_KEY": "fhm_your_key_here"
      }
    }
  }
}

Tools

SEO Scanning

| Tool | Description | |------|-------------| | scan_url | Scan a single URL for SEO issues. Returns score, issues by severity, metadata, links, and images. | | scan_site | Crawl and scan an entire website. Includes duplicate content detection, robots.txt and sitemap analysis. | | get_site_overview | Summary of a previously scanned domain — overall score, top issues, worst pages. | | analyze_page | Deep analysis returning structured data + HTML for the LLM to provide keyword, content quality, and technical insights. |

Real-Time Monitoring (Firehose)

Powered by Ahrefs' crawler (8B+ pages/day). Requires FIREHOSE_MANAGEMENT_KEY.

| Tool | Description | |------|-------------| | firehose_monitor | Quick setup — create a tap and monitoring rule in one step. Ideal after an SEO audit. | | firehose_manage_taps | Create, list, or delete monitoring taps. | | firehose_manage_rules | CRUD rules using Lucene query syntax (e.g., domain:example.com AND added:"pricing"). | | firehose_stream | Consume real-time change events. Supports replay via 24h buffer. |

<details> <summary>Available Lucene query fields</summary>

| Field | Type | Description | |-------|------|-------------| | added | text | Newly inserted content (default search field) | | removed | text | Deleted content | | title | text | Page title | | url | keyword | Full URL (exact match) | | domain | keyword | Domain (e.g., example.com) | | page_category | keyword | ML category (e.g., /News, /Finance) | | page_type | keyword | ML type (e.g., /Article/How_to) | | language | keyword | ISO 639-1 code (e.g., en) | | publish_time | keyword | ISO-8601 datetime | | recent | filter | Recency filter (e.g., 24h, 7d) |

Supports: AND, OR, NOT, phrases ("..."), wildcards (*, ?), ranges ([... TO ...]). Max 25 rules per org.

</details>

Example Workflows

Audit a single page:

"Scan https://example.com for SEO issues"

Crawl an entire site:

"Scan site example.com with max 100 pages"

Deep analysis:

"Analyze https://example.com focusing on keywords and content quality"

Monitor a competitor after audit:

"Set up a Firehose monitor for competitor.com" "Stream the latest events from that monitor"

Track specific content changes:

"Create a Firehose monitor with query: domain:example.com AND added:"pricing" AND language:"en""

SEO Rules (28 total)

| Category | Rules | |----------|-------| | Meta (10) | Title exists, title length, description exists, description length, canonical URL, Open Graph tags, Twitter card, viewport, hreflang, favicon | | Content (7) | H1 exists, H1 count, heading hierarchy, image alt text, word count, internal links, broken links | | Technical (7) | HTTPS, status code, robots meta/noindex, structured data, redirect chains, lang attribute, DOCTYPE | | Performance (4) | Page size, response time, compression, cache headers |

Configuration

All configuration is via environment variables. Defaults work out of the box.

| Variable | Default | Description | |----------|---------|-------------| | WORKER_POOL_SIZE | 4 | Number of worker threads | | DEFAULT_MAX_PAGES | 50 | Default max pages for site crawl | | DEFAULT_MAX_DEPTH | 3 | Default max crawl depth | | REQUEST_TIMEOUT_MS | 15000 | HTTP request timeout | | REQUESTS_PER_SECOND | 5 | Rate limit for outbound requests | | FIREHOSE_MANAGEMENT_KEY | — | Firehose management key (optional, for firehose_* tools) |

See .env.example for a template.

Development

npm install          # Install dependencies
npm run dev          # Run in dev mode (no build needed)
npm run build        # Build
npm run typecheck    # Type check
npm test             # Run tests

Architecture

src/
├── index.ts              # MCP server entry point
├── config/               # Environment-based configuration
├── types/                # TypeScript type definitions
├── tools/                # MCP tool registrations (8 tools)
├── scanner/              # Core scanner engine, fetcher, parser, crawler
├── rules/                # 28 SEO rules across 4 categories
├── workers/              # worker_threads pool for parallel scanning
├── firehose/             # Firehose real-time monitoring client
├── store/                # In-memory result storage
└── utils/                # Rate limiter, URL utils, logger

Companion Tools

Bridddge — Desktop LinkedIn automation built by the same team. If you use seo-mcp to audit your content and want to amplify it on LinkedIn, Bridddge handles outreach, connection requests, and follow-ups with AI-driven personalization. Privacy-first, runs locally.

License

MIT