Bring your real authenticated browser session to AI coding agents. Local-first MCP server + Chrome MV3 extension. No cloud. No telemetry.

@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):

Client	Path
Claude Code	~/.claude.json (or claude mcp add)
Cursor	~/.cursor/mcp.json
VS Code (MCP)	~/.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	~/cline_mcp_settings.json

What the AI agent can do

Tool	Action	Authorization
list_recent_sessions	List recently recorded sessions, newest first (id, origin, ts, event count)	none
search_sessions	Find sessions by text in title/URL/origin plus facets (origin, date range, status, console/network errors). Read-only; returns the same rows as list_recent_sessions.	none
get_session_summary	LLM-readable narrative summary of a session	none
get_session_console_errors	List console errors recorded in a session	none
get_session_network_errors	List failed/notable network requests in a session	none
get_user_action_before_error	Pre-assembled causal chain for a console error: time-ordered timeline (user action → DOM mutation → network/console error), grouped actions/domMutations/networkErrors, the seed error, a deterministic narrative, and windowMs bounding the correlated window. Backward-compatible: errorId/errorTs/actions are still present.	none
generate_playwright_repro	Generate a runnable Playwright test from a session. Emits semantic locators (getByTestId/getByRole/getByPlaceholder/getByText, uniqueness-checked, CSS fallback). Accepts an optional errorId that seeds a console-error-absence assertion so the repro fails while the bug is present and passes once fixed.	none
get_dom_snapshot	Reconstruct the DOM of a recorded session at a given timestamp (forensic)	none
query_dom_history	Two modes: selector mode — timeline of attribute/text changes for one node (as before); window mode (ts + optional windowMs, no selector) — all DOM changes in a time window with target hints.	none
get_page_view	Live, masked, ref-tagged list of interactive elements — target a ref in write actions instead of a CSS selector (cheaper + deterministic than get_dom_snapshot)	per-origin Level 1+
get_element_detail	Full masked detail for one ref from get_page_view (role, name, all aria-*, state, value, href, position, nearby heading, direct interactive children with their refs) — drill in only on the element you need to disambiguate or act on	per-origin Level 1+
request_authorization	Side-panel consent for write actions (Level 3)	per-action user prompt
execute_action	Dispatch a UI action (gated by permission level + destructive blocklist). Pass observe: true on a mutating action (click/type/scroll/enter/dblclick/navigate/…) to also get back a details.viewDelta of what changed (added/removed/changed refs) in one round-trip — instead of re-calling get_page_view	permission level + destructive blocklist
suggest_element	Highlight an element via a non-destructive overlay	per-origin Level 2+
clear_highlight	Remove the highlight overlay	per-origin Level 2+
set_intent	Set the control-shield status banner	per-origin Level 4
request_user_input	Pause and hand a field back to the user, then resume	per-origin Level 4
verify_audit_log	Verify peek's local action audit log (~/.peek/audit.log) is an intact, tamper-evident hash chain. Returns status (intact / broken / truncated / tail-tampered / prefix-tampered / gaps / incomplete-final / head-missing) + entry count and a short message. Read-only.	none

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.

Level	Name	What it allows	Default
0	Off	Recording suppressed, tool surface disabled for the origin
1	Read-only	Read recorded sessions; no action execution	enabled
2	Suggest-only	Read + highlight DOM via overlay; no DOM mutation
3	Act-with-confirm	Read + execute actions, each prompting Allow once / Always for this site / Deny
4	YOLO this session	Read + execute non-destructive actions with no prompt (auto-expires on tab close or 60 min)

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 Level 4 (YOLO — non-destructive actions auto-allow, destructive ones still prompt via the blocklist override). Both are opt-in per origin; the default stays Level 1 (read-only). Level 2 highlight (suggest_element / clear_highlight) and the Level-4 control tools (set_intent, request_user_input) are also implemented. The real-browser dispatch + banner are covered by the Playwright E2E (e2e/smoke.spec.ts).

Database

~/.peek/sessions.db — SQLite (better-sqlite3, WAL mode). Schema in src/db/migrations/. The CLI opens this DB read-mostly; the native host writes it during extension capture; the MCP server reads it for tool calls.

The native host is the only writer. The CLI and MCP server only read (except for the audit log, which is append-only JSONL on disk, not in the DB).

Subpath exports

For consumers building tooling on top of peek:

import { generatePlaywrightRepro } from '@peekdev/mcp/mcp/playwright-repro';
import { loadSessionEvents } from '@peekdev/mcp/mcp/event-blobs';
import { openDb, peekHomeDir } from '@peekdev/mcp/db';
import { buildManifest, installManifests } from '@peekdev/mcp/native-host';

These are the subpath exports the @peekdev/cli package uses. API surface is small but stable.

Versioning & compatibility

Semantic Versioning. Currently 0.1.0-alpha.x — pre-release; tool schemas are stable in spirit but new tools may land in patch releases. See SUPPORTED.md for the compatibility matrix (MCP protocol versions, Chrome stable channels, Node versions).

Per-release changes are recorded in the CHANGELOG.

Privacy

Local-only. No network destinations. No telemetry. The MCP transport is stdio over a child-process pipe — your AI client launches peek-mcp, talks to it over stdin/stdout, and kills it when done. The binary holds no persistent state outside ~/.peek/.

Full data-handling policy: docs/peek/PRIVACY_POLICY.md. Threat model: docs/peek/THREATMODEL.md.

Distribution (maintainer-facing)

This section is for the maintainer's submission workflow at Phase 5 launch. If you're a user, you don't need any of this — just npx @peekdev/cli init.

peek is listed (or queued for listing) on the discovery surfaces below. Each linked file is a submission scaffold with pre-filled metadata audited against the registry's current schema as of 2026-05-30 — not a user-facing install guide.

• Official MCP Registry submission — server.json for registry.modelcontextprotocol.io via mcp-publisher CLI. Downstream registries (PulseMCP, others) ingest from here.
• PulseMCP submission — URL-only form + auto-ingest from the MCP Registry.
• Smithery submission — MCPB bundle uploaded via smithery mcp publish.
• mcp.so submission — web-form submission with the source content paste-ready.
• Claude Code skill standalone install — curl recipe for users who want the Claude Code skill without running peek init.

Launch order is documented in docs/peek/distribution/README.md (CWS first, then the MCP-registry fan-out). The Chrome Web Store listing is submitted + live: chromewebstore.google.com/detail/peek/dmgpmkeneheenpdnfmpjjahnkknkaejb.

Related packages

• @peekdev/cli — the peek init wizard that wires this MCP server into your AI client and installs the native messaging host. Start here.
• @peekdev/extension — the Chrome MV3 extension that records masked browser sessions and writes them to ~/.peek/sessions.db. Available on the Chrome Web Store; contributors can also load it unpacked from packages/peek-extension/chrome-mv3/ for local builds. The npm package stays private (not published to npm).

License

Apache 2.0. The bundled rrweb engine remains MIT-licensed; see NOTICE.

Contributions are accepted under the Developer Certificate of Origin (DCO) — sign your commits with git commit -s. See CONTRIBUTING.md + SECURITY.md.