Lighthouse MCP

Turn Lighthouse audits into coding-agent tasks.

Run repeatable mobile and desktop Lighthouse audits from any compatible MCP client. Receive a bounded implementation backlog with evidence, suggested actions, and measurable acceptance criteria as structured JSON and Markdown.

npx -y mcp-server-lighthouse

Why Lighthouse MCP?

Raw Lighthouse output is designed for diagnostics, not autonomous implementation. It contains metrics, audit details, overlapping insights, and page-controlled text that a coding agent still needs to interpret.

Lighthouse MCP turns that output into a stable workflow:

1. Run Lighthouse for mobile and desktop.
2. Aggregate repeated runs and expose variability.
3. Merge equivalent audits under canonical task IDs.
4. Keep raw metrics out of the implementation backlog.
5. Return at most ten prioritized tasks with evidence and acceptance criteria.

From Audit Noise To An Implementation Plan

Each prioritized task can include:

• affected mobile and desktop profiles;
• resource URLs or DOM selectors;
• estimated time or byte savings;
• deterministic suggested actions;
• measurable acceptance criteria.

See the real CommaLabs JSON report and Markdown report.

Lighthouse results vary with browser version, hardware, network conditions, and page changes. The example demonstrates the report format, not a permanent performance score.

Install

Requirements

• Node.js 20 or later
• Google Chrome or Chromium

The package is an MCP server distributed through npm. Your MCP client starts it as a local stdio process:

npx -y mcp-server-lighthouse

Future releases can be published through the GitHub Actions release workflow once npm trusted publishing is configured for the package.

Claude Desktop

Open Claude Desktop's developer configuration and add:

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

Restart Claude Desktop after saving the configuration. See the official MCP local-server guide.

Claude Code

Add the server with the Claude Code CLI:

claude mcp add lighthouse -- npx -y mcp-server-lighthouse

For local development audits, pass the explicit localhost opt-in:

claude mcp add lighthouse-local -- npx -y mcp-server-lighthouse --local

See the official Claude Code MCP documentation.

Codex

Add the server with the Codex CLI:

codex mcp add lighthouse -- npx -y mcp-server-lighthouse

Or add it to ~/.codex/config.toml:

[mcp_servers.lighthouse]
command = "npx"
args = ["-y", "mcp-server-lighthouse"]

See the official Codex MCP documentation.

VS Code And GitHub Copilot

Create a workspace or user-level .mcp.json file with:

{
  "servers": {
    "lighthouse": {
      "command": "npx",
      "args": ["-y", "mcp-server-lighthouse"]
    }
  }
}

You can also register the server from a terminal:

code --add-mcp '{"name":"lighthouse","command":"npx","args":["-y","mcp-server-lighthouse"]}'

See the official VS Code MCP server documentation.

Cursor

Configure a local stdio MCP server:

• name: lighthouse
• command: npx
• arguments: -y, mcp-server-lighthouse

If your Cursor version supports environment variables for MCP servers, add --local to the server arguments when you need localhost audits.

Other MCP Clients

For clients that accept the standard mcpServers JSON shape, use the Claude Desktop configuration above. Otherwise configure a local stdio server with:

• command: npx
• arguments: -y, mcp-server-lighthouse

Localhost And Private Targets

By default, Lighthouse MCP only accepts publicly routable HTTP and HTTPS URLs. This is the correct default for hosted agents and shared environments.

For developer machines, enable explicit localhost auditing:

npx -y mcp-server-lighthouse --local

Then audit the local app through your MCP client:

{
  "url": "http://localhost:3000",
  "mode": "fast"
}

The opt-in only allows loopback-style targets such as localhost, *.localhost, 127.0.0.0/8, and ::1. Private LAN ranges, link-local addresses, multicast/reserved ranges, and cloud metadata addresses remain blocked.

The environment variable form remains supported for clients that cannot pass extra CLI arguments:

LIGHTHOUSE_MCP_ALLOW_LOCALHOST=true npx -y mcp-server-lighthouse

Tool

analyze_website_performance

Runs Lighthouse against a public HTTP or HTTPS URL:

{
  "url": "https://example.com",
  "mode": "reliable"
}

mode is optional:

• fast: one mobile run and one desktop run.
• reliable: three runs per profile, median results, and variability ranges. This is the default.

What The Report Contains

• Mobile and desktop Performance, Accessibility, Best Practices, and SEO scores
• FCP, Speed Index, LCP, TBT, and CLS distributions
• At most ten canonical prioritized issues
• Up to ten evidence rows per issue
• Resource URLs, DOM selectors, and console error evidence when available
• Suggested actions and measurable acceptance criteria
• Profile warnings when repeated runs vary materially
• Canonical structuredContent validated by the advertised MCP outputSchema
• Equivalent Markdown generated from the same canonical report

If only one profile produces enough successful runs, the report has status: "incomplete". It remains useful for diagnosis but must not be treated as a release baseline.

Coding-Agent Workflow

Treat structuredContent as the source of truth and Markdown as the execution summary:

Inspect the repository before mapping findings to files. Implement issues in prioritizedIssues order, preserve behavior and accessibility, run repository tests after each logical fix, then rerun Lighthouse in reliable mode and compare medians, ranges, and acceptance criteria. Do not claim completion from an incomplete baseline.

Security Model

The URL policy rejects:

• protocols other than HTTP and HTTPS;
• URLs containing embedded credentials;
• localhost names unless LIGHTHOUSE_MCP_ALLOW_LOCALHOST=true is set;
• loopback IPs unless LIGHTHOUSE_MCP_ALLOW_LOCALHOST=true is set;
• private, link-local, multicast, reserved, and metadata-network IPs;
• non-localhost hostnames that resolve to any non-public address.

These checks reduce SSRF exposure but do not replace infrastructure controls. Production operators should run the server in an isolated environment and deny outbound access to private networks and cloud metadata services. Redirects and DNS rebinding are best controlled at the network boundary.

Page-controlled Lighthouse titles, descriptions, URLs, selectors, and snippets are sanitized and length-limited. Consumers must still treat them as untrusted evidence, not agent instructions.

Chrome sandboxing is enabled by default. Only isolated environments that cannot support it should set:

LIGHTHOUSE_CHROME_NO_SANDBOX=true

See SECURITY.md for reporting and deployment guidance.

Local Development

npm install
npm test
npm run check
npm run build

Run a real Chrome smoke audit:

npm run --silent smoke -- https://example.com fast
npm run --silent smoke -- https://example.com reliable

The smoke command writes canonical JSON to stdout and equivalent Markdown to stderr.

Troubleshooting

Chrome cannot be found

Install Google Chrome or Chromium in the environment running the MCP server.

Chrome fails to start in a container

Prefer a container configuration that supports the Chrome sandbox. Set LIGHTHOUSE_CHROME_NO_SANDBOX=true only when the surrounding container or virtual machine provides an equivalent isolation boundary.

The target URL is rejected

Only publicly routable HTTP and HTTPS targets are accepted by default. For a local development server, start Lighthouse MCP with --local and use a loopback URL such as http://localhost:3000. Private network addresses remain blocked.

Contributing

Focused issues and pull requests are welcome. Read CONTRIBUTING.md before changing the report contract, security policy, or MCP transport behavior.

License

MIT