SEO Check MCP

A Model Context Protocol (MCP) server that provides comprehensive SEO analysis tools with actionable fix instructions for AI assistants like Claude Code and Claude Desktop.

Features

• 24 SEO Analysis & Fix Tools
• Actionable Instructions for Claude Code to apply fixes directly
• Dual Transport Support: HTTP (Claude Code) and stdio (Claude Desktop)
• Headless Chrome via Selenium for screenshots and Core Web Vitals

Quick Start

Prerequisites

• Bun runtime
• Chrome/Chromium browser (for screenshot tools)

Installation

git clone git@github.com:muningis/seo-check-mcp.git
cd seo-check-mcp
bun install

Claude Code Integration (HTTP Server)

Claude Code supports HTTP-based MCP servers:

1. Start the server

bun server.mts

2. Configure Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "seo-analysis": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Or add to your global ~/.claude/settings.json:

{
  "mcpServers": {
    "seo-analysis": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

3. Use the tools

The 24 SEO tools will be available in Claude Code automatically.

Claude Desktop Integration (stdio)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "seo-analysis": {
      "command": "bun",
      "args": ["cli.mts"],
      "cwd": "/path/to/seo-check-mcp"
    }
  }
}

Replace /path/to/seo-check-mcp with the actual path to this project.

Available Tools (24 total)

Core Tools

Tool	Description
read-sitemap	Fetches and parses XML sitemaps
read-robots-txt	Fetches robots.txt content
scan	Comprehensive page analysis with optional screenshots
scan-lite	Lightweight page scan (no WebDriver)

Content Analysis

Tool	Description
analyze-content	Keyword density, readability scores, content suggestions
check-readability	Flesch-Kincaid, Gunning Fog, SMOG analysis

Technical SEO

Tool	Description
validate-schema	JSON-LD/Schema.org validation with @graph analysis and completeness scoring
analyze-sitemap	Deep sitemap analysis (freshness, priorities)
check-internal-links	Internal linking structure analysis
find-broken-links	Broken link detection with status codes

Accessibility & Social

Tool	Description
analyze-semantic	Semantic HTML and ARIA accessibility analysis (WCAG 2.1 Level A)
analyze-social-meta	Open Graph, Twitter Cards, and Facebook meta analysis with platform previews

On-Page Optimization

Tool	Description
analyze-meta	Meta tag analysis with SERP preview
analyze-headings	H1-H6 structure validation
analyze-images	Image SEO with alt text suggestions
analyze-url	URL structure and canonical analysis

Competitive Analysis

Tool	Description
compare-pages	Side-by-side SEO comparison
benchmark-seo	Overall SEO score with grades

Fix Tools (Actionable Instructions)

These tools return structured instructions that Claude Code can execute:

Tool	Returns
fix-meta	Title, description, canonical, Open Graph fixes with HTML snippets
fix-images	Alt text fixes with suggested values and CSS selectors
fix-headings	Heading hierarchy fixes with before/after HTML
fix-schema	JSON-LD schema templates ready to add
generate-seo-tasks	Prioritized task list with recommended tools
improve-content	SEO, readability, and structure improvements for local markdown files

Example Workflow with Claude Code

1. Generate a task list

Use the generate-seo-tasks tool on https://example.com

2. Review prioritized improvements

The tool returns tasks sorted by priority (critical → low) with effort/impact ratings:

{
  "url": "https://example.com",
  "score": 62,
  "tasks": [
    {
      "id": "meta-title-missing",
      "description": "Add missing title tag",
      "tool": "fix-meta",
      "priority": "critical",
      "effort": "low",
      "impact": "high"
    }
  ],
  "quickWins": ["meta-title-missing", "meta-canonical"],
  "summary": "SEO Score: 62/100. 1 critical issue(s) need immediate attention."
}

3. Apply fixes

Run fix-meta on https://example.com to get the HTML changes needed

4. Example fix-meta output

{
  "url": "https://example.com",
  "instructions": [
    {
      "action": "replace",
      "target": { "type": "html-tag", "selector": "title" },
      "value": {
        "current": "<title>Home</title>",
        "suggested": "<title>Example - Your Brand Name</title>"
      },
      "reason": "Title too short (4 chars). Should be 50-60 chars with keywords.",
      "priority": "critical",
      "automated": true
    },
    {
      "action": "add",
      "target": { "type": "html-tag", "selector": "head", "tagName": "link" },
      "value": {
        "suggested": "<link rel=\"canonical\" href=\"https://example.com\">"
      },
      "reason": "Missing canonical URL causes duplicate content issues.",
      "priority": "high",
      "automated": true
    }
  ],
  "summary": "2 fixes needed: 1 critical, 1 high priority"
}

Development

# Start HTTP server (for programmatic clients)
bun server.mts
# or
bun run start

# Start stdio server (for Claude Desktop)
bun cli.mts
# or
bun run start:stdio

# Health check (HTTP mode only)
curl http://localhost:3000/health

# Set custom port (HTTP mode only)
MCP_PORT=8080 bun server.mts

# Type check
npx tsc --noEmit

Server Endpoints (HTTP Mode)

Endpoint	Method	Description
/health	GET	Health check, returns { status: 'ok' }
/mcp	POST/GET/DELETE	MCP Streamable HTTP transport endpoint

Architecture

server.mts              # HTTP server (for programmatic clients)
cli.mts                 # Stdio server (for Claude Desktop)
browser/
├── driver.ts           # Headless Chrome WebDriver
├── load-page.ts        # Page loading, Core Web Vitals, screenshots
└── mod.ts
lib/
├── analysis/           # Text analysis & scoring algorithms
├── cache/              # Resource caching
├── config/             # Constants & configuration
├── extraction/         # Page parsing helpers
├── page/               # Page retrieval orchestration
├── suggestions/        # SEO improvement suggestions
├── tools/              # MCP tool implementations (24 tools)
└── types/              # TypeScript interfaces

Adding New Tools

1. Create tool file in lib/tools/your-tool.ts
2. Export registration function: registerYourTool(server: McpServer)
3. Import and call in lib/tools/mod.ts
4. Add to registerAllTools() function

Technical Stack

• Runtime: Bun (primary), Node.js compatible
• HTTP Framework: Hono
• Transports: StdioServerTransport (Claude Desktop), WebStandardStreamableHTTPServerTransport (HTTP clients)
• Browser Automation: Selenium WebDriver with headless Chrome
• Key Dependencies: @modelcontextprotocol/sdk, zod, hono, fast-xml-parser, node-html-parser

License

MIT