MCP Lighthouse

Audit tool for MCP servers. Run 25 automated checks across 5 dimensions and get a compliance score — like Lighthouse, but for your MCP server.

MCP Lighthouse — my-server v1.0

  Protocol    ████████████████████  100
  Schema      ██████████████░░░░░░   70
  Robustness  ████████████████░░░░   75
  Practices   ██████████░░░░░░░░░░   50
  Performance ████████████████████  100

  Overall Score: 83/100

  25 checks: 21 passed, 2 warnings, 2 failed

Why

You built an MCP server. It works in Claude Code. But does it:

• Return proper JSON-RPC 2.0 responses?
• Include inputSchema on every tool?
• Handle invalid tool names without crashing?
• Respond to initialize within a reasonable time?

MCP Lighthouse tests all of this automatically.

Install

pip install mcp-lighthouse

Or from source:

git clone https://github.com/MakiDevelop/mcp-lighthouse.git
cd mcp-lighthouse
pip install -e .

Quick Start

# Audit an MCP server via stdio
mcp-lighthouse scan --stdio "python my_server.py"
mcp-lighthouse scan --stdio "npx @modelcontextprotocol/server-filesystem /"

# Audit a Streamable HTTP endpoint (JSON or SSE responses)
mcp-lighthouse scan --http "http://127.0.0.1:8000/mcp"
mcp-lighthouse scan --http "https://example.com/mcp" --http-header "Authorization=Bearer token"

# Only run specific category
mcp-lighthouse scan --stdio "python my_server.py" --category protocol

# Export markdown report
mcp-lighthouse scan --stdio "python my_server.py" --report audit.md

# Use in CI: fail below 80 (critical failures fail by default)
mcp-lighthouse scan --stdio "python my_server.py" --fail-under 80

# List all checks
mcp-lighthouse list

Checks (25 total)

Protocol Compliance (5 checks, 40% weight) — critical

Schema Quality (10 checks, 25% weight) — warning

Robustness (4 checks, 20% weight) — warning

Best Practices (4 checks, 10% weight) — info

Performance (2 checks, 5% weight) — info

Scoring

• Overall: Weighted average of category scores (protocol 40%, schema 25%, robustness 20%, practices 10%, performance 5%)
• Per category: (passed checks / total checks) * 100
• A single critical failure in Protocol drops that category to 0
• Categories excluded with --category are omitted from the report and score
• The CLI exits with status 1 on critical failures by default; --fail-under adds a score threshold

CLI Reference

mcp-lighthouse scan [OPTIONS]
  --stdio COMMAND       Server command to spawn (mutually exclusive with --http)
  --http URL            Streamable HTTP endpoint (mutually exclusive with --stdio)
  --http-header NAME=VALUE
                        HTTP request header; repeat for multiple headers
  --category CATEGORY   Only run checks in this category
  --timeout SECONDS     Per-check timeout (default: 10)
  --verbose             Show detailed output
  --report PATH         Write markdown report
  --fail-under SCORE    Exit 1 when the overall score is below SCORE
  --no-fail-on-critical Keep exit 0 for critical failures unless --fail-under fails

mcp-lighthouse list
  Lists all available checks

License

MIT