mockpro-mcp

An MCP server that lets Claude Code (and Claude Desktop) mock APIs AND debug any web app in your browser — console logs, network logs, WebSocket frames, DOM inspection, synthetic clicks/typing/navigation.

v3.4 drives MockPro over a local WebSocket (127.0.0.1:27319). No Native Messaging host to install, no chrome.debugger, no "extension is debugging this browser" banner. Every tool the agent calls is also shown live in the extension's MCP Activity tab, so you can watch exactly what it did.

You need: Node.js 18+ · Chrome 136+ · the MockPro extension (free, Chrome Web Store) · an MCP client (Claude Code or Claude Desktop).

Install

Step 1 — Install the MockPro extension (Chrome Web Store)

Open the listing and click Add to Chrome:

https://chromewebstore.google.com/detail/mockpro-api-stream-mocker/liiljkbdpenmgpclbekenhlgpedbcbec

Then grab your extension id (the MCP server needs it):

1. Go to chrome://extensions.
2. Toggle Developer mode (top-right) on.
3. Find the MockPro card and copy the ID — 32 characters, a–p (e.g. liiljkbdpenmgpclbekenhlgpedbcbec).

Don't want to hunt for the id? Open the MockPro Dashboard → MCP Activity tab — it shows the full claude mcp add command with your id already filled in, plus a Copy button.

Step 2 — Register the MCP server (user scope)

Run this once. --scope user writes to ~/.claude.json so every Claude Code project on your machine inherits it — no per-project re-registration:

claude mcp add --scope user --transport stdio mockpro -- npx -y mockpro-mcp \
  --extension-id <YOUR_MOCKPRO_EXTENSION_ID>

Drop --scope user if you'd rather scope it to the current project only.

First time / cautious? Append --readonly to disable the write tools until you trust it:

claude mcp add --scope user --transport stdio mockpro -- npx -y mockpro-mcp \
  --extension-id <ID> --readonly

Turning readonly off later? Re-run without --readonly (it overwrites the entry), or remove first: claude mcp remove mockpro --scope user.

Step 3 — Verify

Open Claude Code, make sure a tab where MockPro runs is open, and ask it to call list_tabs — it should return your open browser tabs. If it errors, the extension isn't connected: open/reload any tab and retry. Watch the Dashboard → MCP Activity tab to confirm the call landed.

Quickstart

Mock an API while building the frontend

You: "Mock GET /api/users to return 3 fake users, then add a 500 variant I can toggle."
Claude: → add_rule × 2 → toggle_rule to flip

Debug a failing UI flow on localhost

You: "The checkout button on localhost:3000 isn't responding — figure out why."
Claude: → list_tabs → query_dom('[data-testid=checkout]', ['disabled']) → read_console_logs(level:'error') → read_network_logs(statusFilter:'4xx,5xx')

Inspect a remote WebSocket

You: "What WebSocket frames is termix.app sending right now?"
Claude: → list_tabs → read_websocket_logs(urlContains:'ssh', direction:'in')

Drive a form end-to-end (v4.0 ref workflow)

You: "Fill the signup form on localhost:3000/signup with test data and submit."
Claude: → snapshot_page                       # ~2KB tree: textbox "Email" [ref=e1], … button "Sign up" [ref=e3]
       → type({ref:'e1', value:'[email protected]'})      # reply includes fresh snapshot
       → type({ref:'e2', value:'secret'})
       → click({ref:'e3'})                    # reply snapshot shows the success page

Install the Claude Code skill (optional, recommended)

The package bundles a skill that teaches Claude how to use these tools — both mocking (missing endpoints, error states, OpenAPI scaffolding) and debugging (console + network + WS logs, DOM inspection, clicks/typing/navigation). Install it once:

npx -y mockpro-mcp install-skill            # → ~/.claude/skills/mockpro (current user, recommended)
npx -y mockpro-mcp install-skill --project  # → ./.claude/skills/mockpro (this repo only)

Restart Claude Code afterward. The skill auto-activates when you ask Claude to mock an API, debug a failing UI flow, drive a form end-to-end, or inspect what a tab is doing.

Flags: --user (default), --project, --dir <path>, --force (overwrite).

Already have an older skill installed? Re-run with --force to pick up v2.0 (debug content): npx -y mockpro-mcp install-skill --force.

Claude Desktop

Edit Claude Desktop's MCP config (this is global per OS user — equivalent to --scope user for Claude Code):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mockpro": {
      "command": "npx",
      "args": ["-y", "mockpro-mcp", "--extension-id", "<YOUR_MOCKPRO_EXTENSION_ID>"]
    }
  }
}

Restart Claude Desktop after editing.

How it works

Claude Code (stdio) ── npx mockpro-mcp ── binds 127.0.0.1:27319
                                              │  WebSocket
                                              ▼
                       MockPro extension service worker ── self.handleMessage

The MCP server binds the WS port (lock-and-die: a second concurrent session exits with a clear message). The MockPro extension's service worker dials the port; tool calls are proxied to the extension over the socket. One session at a time per machine.

Tools

Mocking

• Read (4): get_state, list_rules, get_rule, get_logs (headers redacted by default: Authorization, Cookie, Set-Cookie, Proxy-Authorization).
• Write (8): set_enabled, add_rule, update_rule, delete_rule, toggle_rule, clear_logs, import_rules (merge | replace | append), export_rules.
• Generate (2): mock_from_openapi, record_then_replay — both return suggested rules; commit via import_rules.

Debug (v4.0.0+)

• Read (8): list_tabs, read_console_logs, read_network_logs, read_websocket_logs, query_dom, get_dom_snapshot, wait_for_selector, snapshot_page (compact a11y tree with element refs — call this first).
• Write (8): clear_console_logs, clear_network_logs, clear_websocket_logs, click, type, press_key, select_option, navigate.

v4.0.0 BREAKING: click/type/press_key take ref (from snapshot_page) instead of selector. Requires MockPro extension ≥ 3.0.0. Action replies include a fresh page snapshot (includeSnapshot: false to skip); on stale_ref, call snapshot_page again.

Resources (subscribable)

• mockpro:rule://{id}, mockpro:logs://recent
• mockpro:console://{tabId} + mockpro:console://active alias
• mockpro:network://{tabId} + mockpro:network://active alias
• mockpro:websocket://{tabId} + mockpro:websocket://active alias

--readonly de-registers all write tools at the MCP capability level (debug observation tools stay available).

import_rules merge caveat: merge upserts by reading then writing, non-atomically. Under interleaved writes from another tab/the Dashboard/a parallel client it can degrade to append. Serialize MCP writes client-side, or use replace/append when atomicity matters.

Debug tools require a freshly-loaded tab. Content script is injected at page load; tabs opened BEFORE you installed/reloaded the extension return tab_no_injector. Reload those tabs once.

WebSocket buffer is chatty. Terminals fire 10-20 frames/sec; per-tab cap 500 fills in ~30s. Read with sinceTs or clear_websocket_logs between snapshots.

CLI flags

--extension-id <id>      MockPro extension id (or env MOCKPRO_EXTENSION_ID). Required.
--readonly               Refuse all write tools.
--allow-pattern <regex>  Only allow add/update/import for rules whose urlPattern matches.
--redact-headers <list>  Extra header names to redact, comma-separated.
--config <path>          JSON config file (CLI > env > file > defaults).
-h, --help

stdout is reserved for MCP JSON-RPC frames; all logs go to stderr. redactionDisabled is config-file-only.

Threat model

The WS transport is designed for a trusted single-user host (your personal dev machine):

• Binds 127.0.0.1 only — not reachable from the network.
• Accepts exactly one Origin: chrome-extension://<your extension id>. HTTPS pages can't reach it (Chrome blocks mixed-content ws://); HTTP pages send Origin: null and are rejected.
• Not recommended on shared/multi-user hosts (terminal servers, multi-tenant dev VMs): any local user can reach 127.0.0.1:27319. Per-UID isolation is planned for a later release.

The extension re-validates every frame type and re-enforces --readonly at its own boundary (it does not trust the daemon).

Migrating from v2.x

v3.0 removes the Native Messaging (--transport=native) and CDP (--transport=cdp) transports and the install-host command. See CHANGELOG.md for the full list and cleanup commands (removing the stale Native Messaging manifest).

Local development

pnpm install && pnpm build      # at repo root → extension dist/
cd mockpro-mcp
pnpm install && pnpm build       # compile mockpro-mcp/dist/
pnpm test                        # unit tests (no Chrome required)
pnpm run test:e2e                # real-Chrome E2E — needs Chrome for Testing + ../dist/ built

test:e2e is not run in CI. It requires Chrome for Testing (Chrome stable 148+ blocks --load-extension); resolve it via MOCKPRO_CHROME_BIN or npx @puppeteer/browsers install chrome.

License

MIT — see the root LICENSE file.