peek

@peekdev/mcp

Let your AI coding agent debug what already happened in your real browser — peek reads your locally-recorded sessions (DOM history, console & network errors, the action right before a failure) over MCP and turns them into a runnable Playwright repro. Local-first: peek uploads nothing — what your MCP client does with the data is up to you.

Docs: https://peek.cubenest.in

@peekdev/mcp is two things in one binary:

1. The stdio MCP server that AI coding agents (Claude Code, Cursor, Cline, Windsurf, Continue, Zed) speak to when querying your captured browser sessions.
2. The native messaging host that Chrome's MV3 extension speaks to when writing into ~/.peek/sessions.db.

The same binary handles both roles — chosen by argv. You don't install this package directly in normal use; the @peekdev/cli peek init wizard wires it into your AI client's MCP config and into Chrome's NativeMessagingHosts/.

Requires Node.js ≥ 22. The native better-sqlite3 dependency only ships

prebuilt binaries for Node 22+ — on Node 20 (notably Windows, which has no

C/C++ toolchain by default) the install falls back to compiling from source

and fails. Use Node 22 or newer.

You probably want @peekdev/cli instead

npm install -g @peekdev/cli

peek init

Read on if you're configuring the MCP server manually, building tooling against it, or want the protocol/tool reference.

What this is NOT

• Not a remote MCP server. Peek is local-only: stdio transport over a child-process pipe. There is no HTTP listener, no SSE endpoint, no remote auth. The MCP transport spec's Streamable HTTP variant is out of scope by design.
• Not a write-by-default tool. Read tools are unauthenticated. The write tools (execute_action, request_authorization) are gated by the per-origin permission model (off by default) + the destructive blocklist + the audit-log writer. The cross-process IPC that delivers them to the browser native host (LocalSocketHostBridge ↔ HostSocketServer over ~/.peek/host.sock) is now wired: at Level 3 every action prompts the side-panel confirm banner before it runs. The real-browser MAIN-world dispatch + banner UX are covered by the Playwright E2E (e2e/smoke.spec.ts); the bridge, relay, dispatcher, and confirm logic are unit-tested.
• Not a wrapper around Chrome DevTools Protocol. The server reads recorded events from SQLite; the extension owns capture. No live chrome.debugger access from the MCP server.

One-click install (Cursor)

Click the button (or paste the link into Cursor) and Cursor prompts to add peek to ~/.cursor/mcp.json — no terminal needed. This wires the MCP server only; to capture sessions you still run peek init once (registers the native messaging host) and install the Chrome extension.

Install as a Claude Code plugin

If you use Claude Code, install peek as a plugin in one step:

/plugin marketplace add Cubenest/rrweb-stack

/plugin install peekdev@peek

That wires up this MCP server (18 tools) plus the peek skill. You still need the recorder — run npx @peekdev/cli init once and install the peek Chrome extension — before there are sessions to read. Local-first: peek uploads nothing — what your MCP client does with the data is up to you.

Manual MCP-client config

If peek init doesn't recognize your client, paste this into your client's MCP server registry:

{

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

The @latest tag is required while peek is in alpha: every published version is a prerelease (0.1.0-alpha.*), and a bare npx -y @peekdev/mcp resolves the implicit * range, which doesn't match prereleases (ETARGET: No matching version found for @peekdev/mcp@*). Pinning @latest forces the newest published build.

PEEK_HOME defaults to ~/.peek; set it via env only if you want a non-default capture directory.

The per-user config paths peek init writes to (canonical, see packages/peek-cli/src/lib/init-config.ts):

What the AI agent can do

The full tool list is exposed via the MCP tools/list request (spec 2025-11-25 + back-compat for 2025-03-26). Tool docs ship with the binary via tools/list response description fields.

Permission model (the five levels)

Per-origin, 5 levels (0–4). Default is Level 1 — Read-only. Higher levels are opt-in per origin.

At Level 3 every execute_action call prompts the user via the side-panel banner (unless a one-shot confirmToken from a prior request_authorization is passed). At Level 4 (YOLO) non-destructive actions are auto-allowed with no prompt. Levels 0–2 deny execute_action.

Destructive-action blocklist (cross-level override) — independent of the level, any action whose resolved target text/label matches a destructive term (delete, remove, transfer, send, pay, withdraw, etc. — full base list in permissions/destructive.ts, extensible via ~/.peek/policy.json) always prompts for confirmation. This overrides all levels, including Level 4 YOLO — it is not a separate "Level 5".

Every execute_action and request_authorization call is appended to ~/.peek/audit.log (JSONL, mode 0600 — peek audit log --json prints it), including denied ones. Each entry carries a seq counter and a prevHash field (SHA-256 of the previous line); a sidecar audit.head.json records the tail hash for truncation detection. Run peek audit verify to recompute the chain and confirm it is intact. The log is tamper-evident, not tamper-proof — it detects corruption, truncation, and reordering, but not a determined attacker who recomputes the chain. No keys, no external anchor, no egress.

The write-path is wired end to end: the five-level model, the destructive blocklist, and the audit-log writer are enforced inside peek-mcp (observable via ~/.peek/audit.log), and the cross-process IPC that lets execute_action fire a click in the browser now lands — a LocalSocketHostBridge (MCP process) ↔ HostSocketServer (native host) over ~/.peek/host.sock, a MAIN-world action dispatcher (click/type/navigate/scroll), and a side-panel confirm banner. Both write levels are implemented: Level 3 (act-with-confirm — every action prompts the banner) and **