caido-screenshot-mcp

An MCP server that captures formatted screenshots of Caido Replay request/response pairs, by driving the Screenshot Mode plugin.

Caido has no screenshot API — Screenshot Mode is a frontend-only plugin that renders the DOM to a PNG in the browser. This server reaches it over the Chrome DevTools Protocol, clicks the plugin's own export, and intercepts the resulting image before Electron can open a save dialog. The output is the plugin's real output, written straight to disk.

Requirements

• Node >= 22 (uses the built-in WebSocket; there are no npm dependencies)

• Caido desktop

• The Screenshot Mode plugin installed in Caido

• Caido launched with --remote-debugging-port (see below)

Related MCP server: MCP Browser Screenshot Server

Install

git clone <this-repo> caido-screenshot-mcp
cd caido-screenshot-mcp
npm link            # optional: puts `caido-screenshot` on your PATH

No npm install step — there are no dependencies.

Start Caido with the debug port

The plugin renders inside Caido's window, so the server needs to talk to that window. Launching Caido normally leaves the port closed and every call will fail.

caido-screenshot launch          # quits nothing; starts Caido with the port open

Or manually:

# macOS
open -a Caido --args --remote-debugging-port=9222
# Linux
caido --remote-debugging-port=9222
# Windows
"%LOCALAPPDATA%\Programs\Caido\Caido.exe" --remote-debugging-port=9222

Check everything at once:

caido-screenshot doctor

Use with Claude Code

claude mcp add caido-screenshot --scope user -- node /absolute/path/to/caido-screenshot-mcp/src/server.mjs

Restart Claude Code. Then just ask: "screenshot the current Caido replay session".

Use with any MCP client

{
  "mcpServers": {
    "caido-screenshot": {
      "command": "node",
      "args": ["/absolute/path/to/caido-screenshot-mcp/src/server.mjs"]
    }
  }
}

Tool: caido_screenshot

Examples

Once the server is registered you never name the tool. Describe what you want in plain English and the agent picks it up.

Just capture what's on screen

screenshot the current Caido replay request

The agent calls caido_screenshot and replies with the saved path:

Saved /Users/you/Downloads/caido-screenshot-2026-08-22T13-40-11-002Z.png (438 KB)

Send a request, then capture it

This is the common one. Pair it with the official Caido MCP server, which can send requests — this server captures the result.

send a GET to https://httpbin.org/get in Caido replay and screenshot it

The agent sends the request, maps its returned Replay entry to the populated session, and captures that exact session ID:

Match caido_send_request.entryId to caido_list_replay_sessions[].activeEntryId. Do not create a new session from requestSourceId for response evidence: Caido seeds the request template but does not copy the completed response.

Send a raw request you wrote

Paste the raw HTTP and say what you want:

send this in Caido replay and screenshot it:

POST /post HTTP/1.1
Host: httpbin.org
Content-Type: application/json

{"user":"demo","token":"abc123"}

Pick a specific session

Sessions are named after the request line in Caido's sidebar, so GET /, POST /login and so on:

screenshot the "POST /login" replay session, stacked

That becomes caido_screenshot(session: "POST /login"). Every capture uses Side by Side.

For reliable automation, use the session ID:

caido_screenshot(session_id: "67", require_response: true)

If the session is inside a different or collapsed collection, name both:

screenshot "01 admin create private conversation" from the "OBS AI Assistant IDOR - Fresh Evidence" collection

That becomes caido_screenshot(collection: "OBS AI Assistant IDOR - Fresh Evidence", session: "01 admin create private conversation"). The tool expands the collection before selecting the session and captures it Side by Side.

Heads up: caido_send_request auto-names sessions from the request line, so several targets can all end up called GET /. Rename a session in Caido before capturing if you need to refer to it unambiguously.

Save somewhere specific

screenshot it and save to ~/reports/login-flow.png

Using it from Codex

Start an interactive session and ask the same way:

codex
> screenshot the current Caido replay session

Codex asks for approval the first time. To skip the prompt for this tool, add to ~/.codex/config.toml:

[mcp_servers.caido-screenshot.tools.caido_screenshot]
approval_mode = "auto"   # auto | prompt | writes | approve

codex exec (non-interactive) will not work — it forces approval: never and refuses all MCP tool calls, regardless of per-tool settings. Use an interactive session.

CLI

caido-screenshot                                   # current session -> ~/Downloads
caido-screenshot shot.png                          # explicit path
caido-screenshot shot.png --session "GET /login"
caido-screenshot shot.png --session-id 67
caido-screenshot shot.png --collection "Fresh Evidence" --session "01 admin request"
caido-screenshot doctor
caido-screenshot launch

Environment

Known limitations

These are properties of the plugin, not of this server:

• Long content is cut off. Caido's editors are CodeMirror, which only renders the visible lines. Anything taller than the Caido window is not in the DOM and cannot be captured. Very long responses can come out blank; the server errors instead of writing a near-empty file.

• Headers can be dropped. The DOM-to-image render sometimes omits lines, with visible gaps in the line numbers. Treat these images as illustrative, not as byte-exact evidence — use Caido's own request export when precision matters.

• The layout is fixed to Side by Side. The server deliberately exposes no layout or arrangement option so every evidence screenshot has the same report-ready format.

• Screenshots are not redacted. Whatever is on screen — Authorization, Cookie, Set-Cookie — is captured in full. Review before sharing.

• Request-only Replay sessions are rejected by default. Screenshot Mode can retain its previous preview when the selected session has no response. Pass --allow-no-response only when a request-only screenshot is intentional.

Troubleshooting

License

MIT