MCP Server for AI Agents

Unlighthouse ships a Model Context Protocol server that exposes scanning, history, and pack reports as tools an AI agent can call. The positioning is explicit: this is the sitewide counterpart to Google's Chrome DevTools MCP. The natural workflow is "Unlighthouse triages → Chrome DevTools MCP drills in."

Install

The MCP server ships as a bin in the main unlighthouse package:

npm install -g unlighthouse

Claude Code

claude mcp add unlighthouse -- npx unlighthouse-mcp --site https://example.com

Cursor / other MCP clients

Add this to your client's MCP config:

{
  "mcpServers": {
    "unlighthouse": {
      "command": "npx",
      "args": ["unlighthouse-mcp", "--site", "https://example.com"]
    }
  }
}

Flags

If --site is omitted, the server scans .unlighthouse/ for any hostname with prior scans and picks the one with the most. Useful when an agent is running locally next to existing scan output.

What the agent sees

Twenty tools, projected one-to-one from the command registry. The destructive / live-flow commands are hidden — agents see read-mostly + scan triggers:

Visible (read-mostly): scan_summary, pack_list, pack_run, query_routes, history_list, history_get, route_get, scan_results, scan_meta, scan_status, sites_list, sites_get, compare_run, compare_markdown, compare_findPrevious, assert_evaluate, health, manifest, auditors_list

Visible (write): scan_start — agent can trigger new scans with a URL it picks.

Hidden: scan_cancel, scan_pause, scan_resume, scan_delete, scan_current, scan_rescanAll, route_rescan, history_delete, history_rescan, sites_create, sites_delete, auditors_test, events_subscribe, events_tail

Workflow

Layered output (v1.md §D-028): start with a sub-1KB summary, drill down only when you need detail.

1. pack_list — discover what packs are installed (overview, cwv, images, js-bundle, a11y-quick-wins, seo-basics).
2. history_list — see what scans exist for the configured site.
3. scan_summary — for the scan you care about, get the top-level snapshot. Sub-1KB JSON: category averages, score distribution, worst 5 routes, template groups.
4. pack_run with the scan id and a pack name — get the opinionated report. Output is cached on (scanId, packName, packVersion); pass refresh: true to bust.
5. query_routes / scan_results / route_get — drill into individual routes when the summary or pack flags something worth investigating.

To trigger a fresh scan: scan_start with the URL, then poll scan_status until complete, then jump back to step 3.

Complements Chrome DevTools MCP

If you have both installed, the agent will pick the right one for the question.

Caveats

• No rate limit on scan_start. A misbehaving agent loop can trigger long Lighthouse runs. Lock it down with a custom config (scanner.exclude) if this matters.
• One scan at a time per host process. scan_start while a scan is in flight returns ACTIVE_SCAN_CONFLICT. The agent should poll scan_status instead of retrying.
• Pack output is cached aggressively. Scans are immutable so this is safe. If you ship a custom pack and bump its version, old cached output is invalidated automatically.