mcp-rec

VCR for the Model Context Protocol. Record any MCP server's traffic to a JSONL file, then replay it deterministically — for tests, bug reports, or running your client offline.

Why

MCP servers are great until they aren't:

• Your server passes locally but fails for someone else — and you have no way to share the exact session that broke.
• You want CI tests for your MCP server but you can't pin upstream API responses.
• You want to demo your agent offline.
• You want to bisect "when did this tool start returning empty results?" against a recording.

mcp-rec solves all four by acting as a transparent proxy: it sits between your MCP client and any stdio MCP server, forwards every byte, and writes a JSONL transcript. Later you can replay that transcript as if it were the real server.

Install

pip install mcp-rec
# or
uvx mcp-rec --help

Zero dependencies. Pure Python ≥3.10.

Record

Point your MCP client at mcp-rec record instead of your usual server command:

// claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-rec",
      "args": [
        "record",
        "-o", "/tmp/filesystem-session.jsonl",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/some/path"
      ]
    }
  }
}

Use your client normally. Every JSON-RPC message in both directions is appended to the JSONL file:

{"ts": 1750000001.23, "dir": "client->server", "msg": {"jsonrpc":"2.0","id":1,"method":"tools/list"}}
{"ts": 1750000001.45, "dir": "server->client", "msg": {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}}

Replay

Replace the real server with mcp-rec replay <jsonl> in your client config:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-rec",
      "args": ["replay", "/tmp/filesystem-session.jsonl"]
    }
  }
}

Incoming requests are matched against the recording by (method, params) and the corresponding response is returned with the caller's id rewritten in. Repeated identical requests pop their responses in original order.

Unknown methods return a JSON-RPC -32601 error so your client can tell the recording doesn't cover them.

Use cases

Limitations

• stdio transport only for now. SSE/HTTP transports are on the roadmap.
• Notifications (server-initiated, no id) are replayed once at startup, not interleaved with the request stream.
• The matcher is exact-match on (method, params). If your params include timestamps or random IDs you'll get a -32601 on replay — strip those fields in your client tests, or open an issue and we'll add a matcher config.

Companion projects

• ai-first-scraper-mcp — sample MCP server you can record against.

About the author

Built by yubinkim444, who also makes Kay's Records — an app for iOS and Android.

If this project saved you time, giving the app a try is the nicest way to say thanks.

License

MIT © yubinkim444