SEO Audit

npm (core) npm (cli) npm (local-mcp) License

A comprehensive SEO auditing tool suite. Run audits via CLI, Local MCP (stdio), or Remote MCP (HTTP).

Features

Check	What It Detects
Meta Tags	Missing/invalid title, description, viewport, Open Graph tags
Sitemap	Validate sitemap.xml existence and structure
Robots.txt	Validate robots.txt rules and directives
Broken Links	Scan page for broken/404 links
Headings	Analyze h1–h6 hierarchy compliance
Duplicate Titles	Detect duplicate or poorly formed page titles
Keyword Density	Analyze keyword frequency and density

Packages

All packages are published to npm under the @seo-audit scope.

Package	npm	Description	Type
@seo-audit/core	npm	Shared audit logic	Library
@seo-audit/cli	npm	Command-line interface (seo-audit)	CLI
@seo-audit/local-mcp	npm	MCP server over stdio (seo-audit-mcp)	MCP (local)
@seo-audit/remote-mcp	npm	MCP server over HTTP (seo-audit-remote)	MCP (remote)

Quick Start (No Install)

# CLI — audit any website
npx @seo-audit/cli https://example.com

# Local MCP — run as an MCP server
bunx @seo-audit/local-mcp

Installation

CLI

npm install -g @seo-audit/cli
seo-audit https://example.com

Local MCP (for MCP clients)

npm install -g @seo-audit/local-mcp
seo-audit-mcp

CLI Usage

seo-audit [options] <url>

Arguments:
  url                    Website URL to audit (e.g. https://example.com)

Options:
  -c, --checks <checks>  Comma-separated checks to run.
                         Available: meta-tags, sitemap, robots-txt,
                         broken-links, headings, duplicate-titles,
                         keyword-density
  -t, --timeout <ms>     Request timeout (default: 15000)
  -C, --concurrency <n>  Concurrency for link checking (default: 5)
  -j, --json             Output as JSON
  -V, --version          Show version
  -h, --help             Display help

Examples

# Full audit
npx @seo-audit/cli https://example.com

# Specific checks only
npx @seo-audit/cli https://example.com --checks meta-tags,headings

# JSON output
npx @seo-audit/cli https://example.com --json

# Higher timeout for slow sites
npx @seo-audit/cli https://example.com --timeout 30000

MCP Server Setup

Claude Desktop

Add to claude.json:

{
  "mcpServers": {
    "seo-audit": {
      "command": "bunx",
      "args": ["@seo-audit/local-mcp"]
    }
  }
}

OpenCode

Add to opencode.json:

{
  "mcp": {
    "seo-audit": {
      "type": "local",
      "command": ["bun", "x"."-y", "@seo-audit/local-mcp"],
      "enabled": true
    }
  }
}

MCP Tools

Once connected, the following tools are available:

Tool	Description
audit	Run all SEO checks (or subset)
check_meta_tags	Check meta tags
check_sitemap	Validate sitemap.xml
check_robots_txt	Validate robots.txt
check_broken_links	Find broken links
check_headings	Analyze heading structure
check_duplicate_titles	Check duplicate titles
check_keyword_density	Analyze keyword density

Remote MCP

# Install
npm install -g @seo-audit/remote-mcp

# Run the server
seo-audit-remote

# (Default: http://localhost:3456)

curl -X POST http://localhost:3456/call \
  -H "Content-Type: application/json" \
  -d '{"name":"audit","arguments":{"url":"https://example.com"}}'

Architecture

MCP Clients (Claude Desktop, OpenCode, etc.)
        │                     │
    stdio │                 HTTP │
        ▼                     ▼
┌──────────────┐    ┌──────────────────┐
│ local-mcp    │    │ remote-mcp       │
│ (stdio)      │    │ (Express)        │
└──────┬───────┘    └────────┬─────────┘
       │                     │
       └──────────┬──────────┘
                  ▼
         ┌──────────────┐
         │ core         │
         │ (audit logic)│
         └──────────────┘
                  │
                  ▼
         ┌──────────────┐
         │ cli          │
         │ (commander)  │
         └──────────────┘

Development

This is a Bun monorepo using workspaces.

# Prerequisites
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Build all packages
bun run build

# Run from source (no build needed)
bun run dev:cli      # CLI
bun run dev:local    # Local MCP
bun run dev:remote   # Remote MCP

# Lint, format, typecheck
bun run lint
bun run format:check
bun run typecheck

Publish a Package

cd packages/<name>
npm publish --access public

Tech Stack

Runtime: Bun / Node.js 20+
Language: TypeScript
Bundler: tsdown
Linting/Formatting: oxlint / oxfmt
MCP: @modelcontextprotocol/sdk
HTML Parsing: Cheerio
Validation: Zod
CLI: Commander
HTTP: Express (remote-mcp)

License

MIT