---
title: "MCP Server for AI Agents"
description: "Connect Unlighthouse to Claude Code, Cursor, or any MCP-compatible AI agent. Layered output: sub-1KB scan summaries, opinionated pack reports, drill-down on demand."
canonical_url: "https://unlighthouse.dev/v1/integrations/mcp"
last_updated: "2026-10-03T08:07:18.774Z"
---

# MCP Server for AI Agents

Unlighthouse ships a [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://github.com/ChromeDevTools/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:

```bash
npm install -g unlighthouse
```

### Claude Code

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

### Cursor / other MCP clients

Add this to your client's MCP config:

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

## Flags

| Flag            | Purpose                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| `--site <url>`  | The site the agent will scan / read history for. Resolves to `.unlighthouse/<hostname>/<key>/` on disk. |
| `--root <path>` | Project root (where `.unlighthouse/` lives). Defaults to CWD. Rejected if it escapes CWD.               |
| `--debug`, `-d` | Stream the discover diagnostics + verbose drizzle / storage logs to stderr. Off by default.             |

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](/api-doc). 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](http://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

| Tool                    | Strength                                                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Chrome DevTools MCP** | Single-URL deep dive. Full Lighthouse run + DevTools traces + network/perf/runtime introspection.                           |
| **Unlighthouse MCP**    | Sitewide triage. Crawls every route, layered summaries → packs → drill-down. Identifies *which* URLs warrant the deep dive. |

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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.