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)

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

Parameter	Type	Description
out_path	string	Where to save the PNG. Default ~/Downloads/caido-screenshot-<timestamp>.png
collection	string	Replay collection containing the session. It is expanded automatically.
session	string	Replay session to select first, by sidebar name (e.g. GET /login)
session_id	string	Exact Replay session ID. Preferred because it is unambiguous.
require_response	boolean	Reject request-only sessions and stale previews. Default true.
inline	boolean	Also return the image in the result (large). Default false

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:

Step	Tool	Server
1	caido_send_request	caido
2	caido_list_replay_sessions	caido
3	caido_screenshot(session_id: ...)	caido-screenshot

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

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

Variable	Default	Description
CAIDO_CDP_PORT	9222	Caido's remote debugging port
CAIDO_CDP_TIMEOUT_MS	45000	Per-call CDP timeout

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

Message	Cause
Cannot reach Caido's debug port	Caido not launched with --remote-debugging-port. Quit it and run caido-screenshot launch.
Caido is showing the instance picker	Click Connect on your local instance in the Caido window.
No Screenshot button in the Replay toolbar	No Replay session open, or the Screenshot Mode plugin isn't installed/enabled.
No Replay collection matching "..."	Use the exact collection name shown in the Replay sidebar.
No Replay session matching "..."	The tool expands collection when supplied, then lists the visible session names if no exact match appears.
has no rendered response	The selected session was seeded from a request or has not completed. Capture the session whose activeEntryId equals the send result's entryId.
preview is stale	Screenshot Mode showed a different host/path (or a conflicting visible query). Nothing was saved; retry using the populated session_id. Scheme, encoding, query order, omitted query labels, and Screenshot Mode 0.8.1's missing ? delimiter are normalized automatically.
returned an empty image	Content too long to render. Capture a shorter request/response.

License

MIT