mcp-rec

# 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. [](https://pypi.org/project/mcp-rec/) []() []() []() --- ## 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 ```bash 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: ```jsonc // 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: ```json {"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 <j…