Lightspeed MCP

A Model Context Protocol (MCP) server that runs Google Lighthouse so LLM clients can audit performance, accessibility, SEO, security, and Core Web Vitals on real URLs—using the same engine as Chrome DevTools, with structured scores and recommendations instead of ad-hoc scraping.

Published on npm as @lightspeedrun/mcp.

Lightspeed MCP vs Lighthouse CLI

This package exposes Lighthouse through MCP tools (discoverable schemas, prompts, and resources) for agents inside Cursor, VS Code, Claude Desktop, and similar hosts.

• Lighthouse CLI / CI: Best when you want fixed scripts, JSON/HTML reports on disk, and deterministic pipelines (GitHub Actions, scheduled jobs). No MCP schema or host process—lower overhead when an agent is not in the loop.

• Lightspeed MCP: Best when a coding agent should iterate on audits (compare mobile vs desktop, dig into LCP, re-run after a change) inside the IDE, with tools the model can compose. Each run launches Chrome and executes Lighthouse, so it is heavier than pure static analysis—use budgets and focused tools when context is tight.

Key features

• Official Lighthouse audits — scores and diagnostics aligned with Chrome’s implementation.
• LLM-oriented tools — typed inputs and summarized outputs for run_audit, Core Web Vitals, SEO, accessibility, PWA, security, and resource analysis.
• stdio by default — npx @lightspeedrun/mcp@latest works with standard MCP clients; optional Streamable HTTP mode for hosted deployments (see Standalone / remote MCP).

Requirements

• Node.js 20 or newer
• Google Chrome or Chromium on the machine that runs the server (Lighthouse drives a real browser)

Getting started

Install the server through your MCP client using npx.

Standard config (works in most clients):

{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["@lightspeedrun/mcp@latest"]
    }
  }
}

Some clients behave better with a non-interactive install:

{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["-y", "@lightspeedrun/mcp@latest"]
    }
  }
}

In VS Code, use the Amp extension settings or settings.json:

"amp.mcpServers": {
  "lightspeed": {
    "command": "npx",
    "args": ["@lightspeedrun/mcp@latest"]
  }
}

Amp CLI

amp mcp add lightspeed -- npx @lightspeedrun/mcp@latest

{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["@lightspeedrun/mcp@latest"]
    }
  }
}

claude mcp add lightspeed npx @lightspeedrun/mcp@latest

Follow the MCP install guide, then use the standard config above.

See Configuring MCP Servers. Example for cline_mcp_settings.json:

{
  "mcpServers": {
    "lightspeed": {
      "type": "stdio",
      "command": "npx",
      "timeout": 120,
      "args": ["-y", "@lightspeedrun/mcp@latest"],
      "disabled": false
    }
  }
}

codex mcp add lightspeed npx "@lightspeedrun/mcp@latest"

Or in ~/.codex/config.toml:

[mcp_servers.lightspeed]
command = "npx"
args = ["@lightspeedrun/mcp@latest"]

See Codex MCP configuration.

Use /mcp add in the Copilot CLI, or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "lightspeed": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["@lightspeedrun/mcp@latest"]
    }
  }
}

See Copilot CLI — MCP.

One-click install

Manual install

Cursor Settings → MCP → Add new MCP server. Use Command type: command npx, args @lightspeedrun/mcp@latest (or a single command string if your UI expects it).

droid mcp add lightspeed "npx @lightspeedrun/mcp@latest"

Or use /mcp in Factory Droid for the interactive UI. See Factory MCP.

Follow Gemini CLI — MCP servers and use the standard config.

Manual: Advanced settings → Extensions → Add custom extension → type STDIO, command npx @lightspeedrun/mcp@latest.

Use /mcp → add server, or add to .junie/mcp/mcp.json:

{
  "mcpServers": {
    "Lightspeed": {
      "command": "npx",
      "args": ["-y", "@lightspeedrun/mcp@latest"]
    }
  }
}

See Junie MCP configuration.

Example .kiro/settings/mcp.json:

{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["@lightspeedrun/mcp@latest"]
    }
  }
}

See Kiro MCP servers.

Use Program → Install → Edit mcp.json and paste the standard config.

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "lightspeed": {
      "type": "local",
      "command": ["npx", "@lightspeedrun/mcp@latest"],
      "enabled": true
    }
  }
}

See opencode MCP servers.

In VS Code or IntelliJ: Qodo Gen → Connect more tools → Add new MCP → paste the standard config.

Use the install badges at the top of this section, or the MCP servers doc.

code --add-mcp '{"name":"lightspeed","command":"npx","args":["@lightspeedrun/mcp@latest"]}'

Settings → AI → Manage MCP Servers → Add, or run /add-mcp and paste the standard config. See Warp MCP.

Follow Windsurf MCP and use the standard config.

Configuration

Pass these flags in the args array of your MCP config (after @lightspeedrun/mcp@latest), or set the noted environment variables when using HTTP mode.

Chrome / Lighthouse launch

| Option | Description | | --- | --- | | --headless | Run Chrome in headless mode (boolean flag). | | --no-headless | Prefer headed Chrome (e.g. sites that block headless). | | --user-data-dir <path> | Chrome user data directory (persistent profile). | | --profile-directory <name> | Profile folder name inside the user data dir. | | --profile-path <path> | Sets user data dir + profile from a full profile path. | | --chrome-path <path> | Path to Chrome/Chromium binary. | | --chrome-port <port> | Remote debugging port (alias of --remote-debugging-port). | | --remote-debugging-port <port> | Fixed debugging port for Chrome. | | --chrome-flag <flag> | Extra Chrome flag (repeat for multiple). |

Streamable HTTP server (optional)

Run with --http when you want an HTTP MCP transport instead of stdio (e.g. behind TLS on Fly, Docker, or a VPS).

| Option / variable | Description | | --- | --- | | --http | Start Streamable HTTP server (Express). | | --http-port <port> | Port (default: 3333, or MCP_HTTP_PORT, or PORT). | | --http-host <host> | Bind address (default 0.0.0.0 or MCP_HTTP_HOST). | | MCP_HTTP_TOKEN | If set, require Authorization: Bearer … on MCP routes. | | MOESIF_APPLICATION_ID | Optional Moesif usage analytics for MCP routes. | | MOESIF_COMPANY_ID | Optional Moesif company id for B2B attribution. |

Example with HTTP:

npx @lightspeedrun/mcp@latest --http --http-host 0.0.0.0 --http-port 3333

Standalone / remote MCP (Streamable HTTP)

If you already host this server over HTTPS (for example with the Dockerfile.mcp image from the GitHub repository), point clients that support URL transport at your endpoint (MCP is served at /; /mcp is an alias). Health check: GET /health.

{
  "mcpServers": {
    "lightspeed": {
      "url": "https://your-host.example/"
    }
  }
}

If you set MCP_HTTP_TOKEN, configure your client’s bearer token / headers per its docs.

A public reference deployment is documented in the monorepo; for Smithery or Fly.io setup, see the root README.md in efd1/lightspeed.

Tools

• run_audit — Full Lighthouse audit for a URL.
• get_accessibility_score — Accessibility score and guidance.
• get_seo_analysis — SEO-oriented audit slice.
• check_pwa_readiness — PWA checks.

• get_performance_score — Performance category score.
• get_core_web_vitals — LCP, INP, CLS, etc.
• compare_mobile_desktop — Mobile vs desktop comparison.
• check_performance_budget — Thresholds / budgets.
• get_lcp_opportunities — LCP optimization hints.

• find_unused_javascript — Unused JS opportunities.
• analyze_resources — Images, JS, CSS, fonts.
• get_security_audit — HTTPS, CSP, and related security signals.

Prompts and resources are registered on the server for discovery by compatible clients.

Security

Lightspeed MCP is not a security boundary. It runs Lighthouse in a real browser and can fetch arbitrary URLs you pass in tool arguments—only use it with hosts and credentials you trust, and follow MCP security best practices.

For remote HTTP mode, always set MCP_HTTP_TOKEN (or equivalent) in production and restrict network access as appropriate.

Docker

Example (from monorepo root; Chromium is included in the image):

docker build -f Dockerfile.mcp -t lightspeed-mcp .
docker run --rm -p 8080:8080 -e MCP_HTTP_TOKEN=secret lightspeed-mcp

The default image listens on PORT (often 8080). See the repository Dockerfile.mcp and fly.toml for production hardening.

Development (monorepo)

This package is developed inside efd1/lightspeed under packages/lightspeed-mcp-server.

pnpm install
pnpm exec turbo build --filter=@lightspeedrun/mcp
pnpm --filter @lightspeedrun/mcp start
pnpm --filter @lightspeedrun/mcp dev

Publish to npm (requires login and @lightspeedrun scope access):

pnpm exec turbo build --filter=@lightspeedrun/mcp
cd packages/lightspeed-mcp-server && npm publish

Run from a local build (no npm):

{
  "mcpServers": {
    "lightspeed": {
      "command": "node",
      "args": ["/absolute/path/to/repo/packages/lightspeed-mcp-server/dist/index.js"]
    }
  }
}

License

MIT — see LICENSE.