LightScout MCP

Part of the TestScout MCP Suite — AI-powered QA tools for modern development teams.

Core Web Vitals analysis powered by Lighthouse. Runs as an MCP server for AI coding tools (Claude Code, Cursor, Windsurf, etc.) or as a standalone CLI for CI pipelines and terminals. Four tools: analyze a URL, compare two URLs, check against thresholds, or crawl an entire site.

Requirements

• Node.js >= 18
• Google Chrome or Chromium

MCP Server Setup

Claude Code

claude mcp add lightscout -- npx -y lightscout-mcp

Cursor, VS Code, Windsurf, Cline, Roo Code, Gemini CLI

All use the same mcpServers JSON format. Add this to the appropriate config file:

{
  "mcpServers": {
    "lightscout": {
      "command": "npx",
      "args": ["-y", "lightscout-mcp"]
    }
  }
}

| Client | Config file | |-------------------|---------------------------------------------| | Cursor | ~/.cursor/mcp.json | | VS Code (Copilot) | .vscode/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Cline | Settings > MCP > Edit Config | | Roo Code | .roo/mcp.json | | Gemini CLI | ~/.gemini/settings.json |

Zed

Zed uses context_servers instead of mcpServers:

{
  "context_servers": {
    "lightscout": {
      "command": "npx",
      "args": ["-y", "lightscout-mcp"]
    }
  }
}

CLI

Install

npm install -g lightscout-mcp

Try without installing

npx -p lightscout-mcp lightscout analyze https://example.com

Commands

lightscout analyze <url> [--device mobile|desktop] [--categories perf,a11y,seo,best-practices]
lightscout compare <urlA> [urlB] [--device mobile|desktop]
lightscout crawl <url> [--max-pages N] [--device mobile|desktop]
lightscout check <url> [--perf 90] [--lcp 2500] [--fcp 3000] [--cls 0.1] [--tbt 300] [--ttfb 1800]

Examples

Analyze a single page:

lightscout analyze https://example.com
lightscout analyze https://example.com --device desktop --categories performance,accessibility

Compare two URLs, or the same URL on mobile vs desktop:

lightscout compare https://a.com https://b.com
lightscout compare https://example.com                    # mobile vs desktop

Crawl a site and audit discovered pages:

lightscout crawl https://example.com --max-pages 5

CI quality gate (exits 1 on failure):

lightscout check https://example.com --perf 90 --lcp 2500

Tools

analyze_performance

Run Lighthouse on a URL. Returns performance scores, Core Web Vitals (LCP, FCP, CLS, TBT, SI, TTFB) with good/needs-improvement/poor ratings, top recommendations sorted by impact, and diagnostics.

| Parameter | Type | Required | Description | |--------------|-------------------------------|----------|----------------------------------------------------------------| | url | string | yes | URL to analyze | | device | "mobile" | "desktop" | no | Device emulation (default: mobile) | | categories | string[] | no | Lighthouse categories (default: ["performance"]) |

compare_performance

Compare Core Web Vitals between two URLs, or the same URL on mobile vs desktop. Shows per-metric deltas with winner indicators.

| Parameter | Type | Required | Description | |-----------|-------------------------------|----------|----------------------------------------------------------------| | urlA | string | yes | First URL | | urlB | string | no | Second URL. If omitted, compares urlA mobile vs desktop | | device | "mobile" | "desktop" | no | Device emulation when comparing two URLs (default: mobile) |

check_threshold

Pass/fail check against performance thresholds. Useful for CI quality gates.

| Parameter | Type | Required | Description | |--------------|-------------------------------|----------|---------------------------------------------------| | url | string | yes | URL to check | | device | "mobile" | "desktop" | no | Device emulation (default: mobile) | | thresholds | object | no | Custom thresholds (see defaults below) |

Default thresholds use Google's "poor" boundary -- only fails if metrics are genuinely bad:

| Metric | Default (fail if worse) | |-------------|------------------------| | performance | < 50 | | LCP | > 4000ms | | FCP | > 3000ms | | CLS | > 0.25 | | TBT | > 600ms | | TTFB | > 1800ms |

crawl_site

Discover pages on a site (via sitemap.xml or link crawling) and run Lighthouse on each. Returns per-page results plus site-wide summary with avg/min/max scores and common issues.

| Parameter | Type | Required | Description | |------------|-------------------------------|----------|---------------------------------------------------| | url | string | yes | Site URL or homepage to crawl | | device | "mobile" | "desktop" | no | Device emulation (default: mobile) | | maxPages | number | no | Maximum pages to analyze (default: 20, max: 20) |

Pages are discovered via sitemap.xml first, falling back to link crawling. Up to 3 Lighthouse runs execute in parallel.

CWV Rating Thresholds

| Metric | Good | Needs Improvement | Poor | |--------|------|-------------------|------| | LCP | <= 2500ms | 2500-4000ms | > 4000ms | | FCP | <= 1800ms | 1800-3000ms | > 3000ms | | CLS | <= 0.1 | 0.1-0.25 | > 0.25 | | TBT | <= 200ms | 200-600ms | > 600ms | | SI | <= 3400ms | 3400-5800ms | > 5800ms | | TTFB | <= 800ms | 800-1800ms | > 1800ms |

Notes

• TBT (Total Blocking Time) is used instead of INP/FID because Lighthouse runs lab-only tests with no real user interaction.
• Up to 3 concurrent Lighthouse runs (semaphore-controlled).
• Chrome is launched headless and killed after each audit.
• MCP responses are token-optimized with condensed metrics and compact JSON.

TestScout MCP Suite

LightScout is the first tool in the TestScout MCP Suite. More tools are coming:

| Tool | Description | Status | |------|-------------|--------| | lightscout-mcp | Core Web Vitals & Lighthouse analysis | Available | | testscout-diagnose | Error triage & root cause analysis | Coming soon | | testscout-scrape | Structured data extraction for testing | Coming soon | | testscout-plan | AI test plan & code generation | Coming soon | | testscout-load | Load test generation & analysis | Coming soon | | testscout-maintain | Self-healing test maintenance | Coming soon |

Follow development at testscout.dev.

License

MIT