mcp-recorder — VCR.py for MCP servers

1<p align="center">
2  <img src="hero.gif" alt="mcp-recorder demo" width="720" />
3</p>
4 
5# mcp-recorder — VCR.py for MCP servers
6 
7Record, replay, and verify Model Context Protocol interactions for deterministic testing.
8 
9[![PyPI version](https://img.shields.io/pypi/v/mcp-recorder.svg)](https://pypi.org/project/mcp-recorder/)
10[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
11[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
12[![CI](https://github.com/devhelmhq/mcp-recorder/actions/workflows/check.yml/badge.svg)](https://github.com/devhelmhq/mcp-recorder/actions)
13 
14MCP servers break silently. Tool schemas change, prompts drift, responses shift. Without wire-level regression tests, you find out from your users. mcp-recorder captures the full protocol exchange into a cassette file and lets you test from both sides.
15 
16## Record. Replay. Verify.
17 
18Try it right now — a [`scenarios.yml`](scenarios.yml) and a public demo server at `https://mcp.devhelm.io` are included so you can run this without any setup:
19 
20```bash
21pip install mcp-recorder
22 
23# 1. Record cassettes from a scenarios file (zero code)
24mcp-recorder record-scenarios scenarios.yml
25 
26# 2. Inspect what was captured
27mcp-recorder inspect cassettes/demo_walkthrough.json
28 
29# 3. Verify your server hasn't regressed — compare responses to the recording
30mcp-recorder verify --cassette cassettes/demo_walkthrough.json --target https://mcp.devhelm.io
31 
32# 4. Replay as a mock server — test your client without the real server
33# (starts a local server on port 5555, point your MCP client at it)
34mcp-recorder replay --cassette cassettes/demo_walkthrough.json
35 
36# Works with stdio servers too — no HTTP wrapper needed
37mcp-recorder verify --cassette cassettes/golden.json \
38  --target-stdio "node dist/index.js"
39```
40 
41One cassette. Three modes. HTTP and stdio transports. Full coverage for both client and server testing.
42 
43## Contents
44 
45- [Install](#install)
46- [How It Works](#how-it-works)
47- [Scenarios](#scenarios)
48- [CLI Usage](#cli-usage)
49- [pytest Integration](#pytest-integration)
50- [Python API](#python-api)
51- [Configuration](#configuration)
52- [Cassette Format](#cassette-format)
53- [CLI Reference](#cli-reference)
54- [CI Integration](#ci-integration)
55- [Roadmap](#roadmap)
56- [Contributing](#contributing)
57 
58## Install
59 
60```bash
61pip install mcp-recorder
62```
63 
64Or with [uv](https://docs.astral.sh/uv/):
65 
66```bash
67uv add mcp-recorder
68```
69 
70## How It Works
71 
72mcp-recorder captures the full MCP exchange into a cassette file. It supports both HTTP (Streamable HTTP / SSE) and stdio (subprocess) transports — the transport is an implementation detail, the cassette format is the same. That single recording unlocks two testing directions:
73 
74```
75Record:   Client -> mcp-recorder (proxy) -> Real Server -> cassette.json
76                                            (HTTP or stdio subprocess)
77 
78Replay:   Client -> mcp-recorder (mock)  -> cassette.json     (test your client)
79Verify:   mcp-recorder (client mock) -> Real Server            (test your server)
80```
81 
82**Replay** serves recorded responses back to your client. No real server, no credentials, no network.
83 
84**Verify** sends recorded requests to your (updated) server and compares the actual responses to the golden recording. Catches regressions after changing tools, schemas, or prompts.
85 
86## Scenarios
87 
88Define what to test in a YAML file. No Python scripts, no boilerplate — works with MCP servers written in any language.
89 
90```yaml
91schema_version: "1.0"
92 
93target: http://localhost:3000
94 
95redact:
96  server_url: true
97  env:
98    - API_KEY
99  patterns:
100    - "sk-[a-zA-Z0-9]+"
101 
102scenarios:
103  tools_and_schemas:
104    description: "Discover tools and call search"
105    actions:
106      - list_tools
107      - call_tool:
108          name: search
109          arguments:
110            query: "test"
111 
112  error_handling:
113    description: "Invalid inputs return proper errors"
114    actions:
115      - call_tool:
116          name: search
117          arguments: {}
118```
119 
120For stdio MCP servers, use a target object instead of a URL:
121 
122```yaml
123target:
124  command: "node"
125  args: ["dist/index.js"]
126  env:
127    API_KEY: "test-key"
128  cwd: "./server"
129```
130 
131| Target field | Required | Description |
132|---|---|---|
133| `command` | yes | Executable to spawn |
134| `args` | no | List of command-line arguments |
135| `env` | no | Extra environment variables (merged with current env) |
136| `cwd` | no | Working directory for the subprocess |
137 
138### Environment Variables
139 
140String values in `scenarios.yml` support `${VAR}` interpolation — the variable is resolved from the current environment at load time. Use `${VAR:-default}` to provide a fallback when the variable is not set. If a referenced variable is missing and no default is provided, loading fails with a clear error.
141 
142```yaml
143schema_version: "1.0"
144 
145target:
146  command: "node"
147  args: ["dist/index.js"]
148  env:
149    API_KEY: "${API_KEY}"
150    REGION: "${AWS_REGION:-us-east-1}"
151 
152redact:
153  env:
154    - API_KEY
155 
156scenarios:
157  authenticated_search:
158    description: "Search with a real API key"
159    actions:
160      - list_tools
161      - call_tool:
162          name: search
163          arguments:
164            query: "test"
165```
166 
167This works naturally with CI systems. In GitHub Actions, expose repository secrets as environment variables and `scenarios.yml` picks them up:
168 
169```yaml
170# .github/workflows/mcp-test.yml
171jobs:
172  test:
173    runs-on: ubuntu-latest
174    env:
175      API_KEY: ${{ secrets.API_KEY }}
176    steps:
177      - uses: actions/checkout@v4
178      - run: pip install mcp-recorder
179      - run: mcp-recorder record-scenarios scenarios.yml -o cassettes/
180```
181 
182Interpolation applies to all string values: `target` URLs, `target.env` values, tool arguments, resource URIs, etc. Non-string values (numbers, booleans) are left unchanged. Dictionary keys are not expanded.
183 
184Record all scenarios at once, or pick one:
185 
186```bash
187mcp-recorder record-scenarios scenarios.yml
188mcp-recorder record-scenarios scenarios.yml --scenario tools_and_schemas
189```
190 
191Each scenario key becomes the cassette filename (`tools_and_schemas` -> `tools_and_schemas.json`). Protocol handshake (`initialize` + `notifications/initialized`) is handled automatically.
192 
193Supported actions:
194 
195| Action | Description |
196|---|---|
197| `list_tools` | Call `tools/list` |
198| `call_tool` | Call `tools/call` with `name` and `arguments` |
199| `list_prompts` | Call `prompts/list` |
200| `get_prompt` | Call `prompts/get` with `name` and optional `arguments` |
201| `list_resources` | Call `resources/list` |
202| `read_resource` | Call `resources/read` with `uri` |
203 
204## CLI Usage
205 
206### Interactive Recording
207 
208Start the proxy pointing at your MCP server:
209 
210```bash
211# HTTP target
212mcp-recorder record \
213  --target http://localhost:8000 \
214  --port 5555 \
215  --output golden.json
216 
217# stdio target — spawns the server as a subprocess
218mcp-recorder record \
219  --target-stdio "node dist/index.js" \
220  --target-env API_KEY=test-key \
221  --output golden.json
222```
223 
224Point your MCP client at `http://localhost:5555` and interact normally. Press `Ctrl+C` when done — the cassette is saved.
225 
226Works with remote servers too:
227 
228```bash
229mcp-recorder record \
230  --target https://mcp.example.com/v1/mcp \
231  --redact-env API_KEY \
232  --output golden.json
233```
234 
235For automated recording, see [Scenarios](#scenarios).
236 
237### Verify
238 
239After making changes to your server, verify nothing broke:
240 
241```bash
242# HTTP target
243mcp-recorder verify --cassette golden.json --target http://localhost:8000
244 
245# stdio target
246mcp-recorder verify --cassette golden.json \
247  --target-stdio "node dist/index.js" \
248  --target-env API_KEY=test-key
249```
250 
251```
252Verifying golden.json against http://localhost:8000
253 
254  1. initialize          [PASS]
255  2. tools/list          [PASS]
256  3. tools/call [search] [FAIL]
257       $.result.content[0].text: "old output" != "new output"
258  4. tools/call [analyze] [PASS]
259 
260Result: 3/4 passed, 1 failed
261```
262 
263Exit code is non-zero on any diff — plug it straight into CI.
264 
265For fields that change every run, skip them by name or by exact path:
266 
267```bash
268mcp-recorder verify --cassette golden.json --target http://localhost:8000 \
269  --ignore-fields timestamp \
270  --ignore-paths '$.result.content[0].text.metadata.requestId'
271```
272 
273When both values are JSON-encoded strings (common in MCP `content[0].text`), mcp-recorder automatically parses and compares them structurally instead of as raw strings.
274 
275When a change is intentional, update the cassette:
276 
277```bash
278mcp-recorder verify --cassette golden.json --target http://localhost:8000 --update
279```
280 
281### Replay
282 
283Serve recorded responses without the real server:
284 
285```bash
286mcp-recorder replay --cassette golden.json
287```
288 
289A mock server starts on port `5555`. Point your client at it. No network, no credentials, same responses every time.
290 
291### Inspect
292 
293```bash
294mcp-recorder inspect golden.json
295```
296 
297```
298golden.json
299  Recorded: 2026-02-17 20:25:23
300  Server:   Test Calculator v2.14.5
301  Protocol: 2025-11-25
302  Target:   http://127.0.0.1:8000
303 
304  Interactions (9):
305    1. initialize -> 200 SSE (7ms)
306    2. notifications/initialized -> 202 (1ms)
307    3. tools/list -> 200 SSE (22ms)
308    4. tools/call [add] -> 200 SSE (18ms)
309    ...
310 
311  Summary: 6 requests, 1 notification, 2 lifecycle
312```
313 
314## pytest Integration
315 
316The pytest plugin activates automatically on install. Mark tests with a cassette and use the `mcp_replay_url` fixture:
317 
318```python
319import pytest
320from fastmcp import Client
321 
322@pytest.mark.mcp_cassette("cassettes/golden.json")
323async def test_tool_call(mcp_replay_url):
324    async with Client(mcp_replay_url) as client:
325        result = await client.call_tool("add", {"a": 2, "b": 3})
326        assert result.content[0].text == "5"
327```
328 
329For server regression testing, use `mcp_verify_result`:
330 
331```python
332@pytest.mark.mcp_cassette("cassettes/golden.json")
333def test_no_regression(mcp_verify_result):
334    assert mcp_verify_result.failed == 0, mcp_verify_result.results
335```
336 
337To ignore volatile fields, pass them via the marker:
338 
339```python
340@pytest.mark.mcp_cassette(
341    "cassettes/golden.json",
342    ignore_fields=["timestamp"],
343    ignore_paths=["$.result.metadata.requestId"],
344)
345def test_no_regression(mcp_verify_result):
346    assert mcp_verify_result.failed == 0
347```
348 
349```bash
350pytest                                        # replay from cassettes (default)
351pytest --mcp-target http://localhost:8000      # verify against live HTTP server
352pytest --mcp-target-stdio "node dist/index.js" # verify against stdio server
353pytest --mcp-record-mode=auto                  # replay if cassette exists, skip if not
354```
355 
356Each test gets an isolated server on a random port. No manual server management.
357 
358## Python API
359 
360For programmatic recording:
361 
362```python
363from mcp_recorder import RecordSession
364 
365async with RecordSession(
366    target="http://localhost:8000",
367    output="golden.json",
368) as client:
369    await client.list_tools()
370    await client.call_tool("add", {"a": 2, "b": 3})
371```
372 
373`RecordSession` starts a recording proxy, runs `initialize` automatically, and saves the cassette on exit. Supports all redaction options (`redact_server_url`, `redact_env`, `redact_patterns`).
374 
375## Configuration
376 
377### Matching Strategies
378 
379| Strategy | Flag | Description |
380|---|---|---|
381| **Method + Params** | `method_params` | Match on JSON-RPC `method` and `params`, ignoring `_meta` (default) |
382| **Sequential** | `sequential` | Return next unmatched interaction in recorded order |
383| **Strict** | `strict` | Full structural equality of the request body including `_meta` |
384 
385### Secret Redaction
386 
387Redaction is explicit — no magic scanning, no hidden behavior. You control exactly what gets scrubbed.
388 
389**`--redact-server-url`** (enabled by default) — strips the URL path from `metadata.server_url`, keeping only scheme + host. Handles API keys in URLs like `https://mcp.firecrawl.dev/<key>/mcp`.
390 
391```bash
392mcp-recorder record --target https://mcp.firecrawl.dev/$FIRECRAWL_KEY/mcp
393# metadata shows: https://mcp.firecrawl.dev/[REDACTED]
394 
395mcp-recorder record --target http://localhost:8000 --no-redact-server-url
396# metadata shows full URL
397```
398 
399**`--redact-env VAR_NAME`** — reads the env var's value and replaces it in metadata and response bodies. Request bodies are never modified to preserve replay and verify integrity.
400 
401```bash
402mcp-recorder record \
403  --target https://mcp.firecrawl.dev/$FIRECRAWL_KEY/mcp \
404  --redact-env FIRECRAWL_KEY
405```
406 
407**`--redact-patterns REGEX`** — for values not in environment variables. Same scope (metadata + responses only).
408 
409```bash
410mcp-recorder record --target http://localhost:8000 \
411  --redact-patterns "sk-[a-zA-Z0-9]+" \
412  --redact-patterns "session-[0-9a-f]{32}"
413```
414 
415In scenarios files, redaction is configured in the `redact` block and applies to all cassettes from that file. HTTP headers (Authorization, Cookie, etc.) are not stored in cassettes — the proxy only captures JSON-RPC message bodies.
416 
417## Cassette Format
418 
419Cassettes store JSON-RPC messages at the protocol level:
420 
421```json
422{
423  "version": "1.0",
424  "metadata": {
425    "recorded_at": "2026-02-17T20:25:23Z",
426    "server_url": "http://127.0.0.1:8000",
427    "transport_type": "http",
428    "protocol_version": "2025-11-25",
429    "server_info": { "name": "Test Calculator", "version": "2.14.5" }
430  },
431  "interactions": [
432    {
433      "type": "jsonrpc_request",
434      "request": {
435        "jsonrpc": "2.0", "id": 0, "method": "initialize",
436        "params": { "protocolVersion": "2025-11-25", "capabilities": {} }
437      },
438      "response": {
439        "jsonrpc": "2.0", "id": 0,
440        "result": {
441          "protocolVersion": "2025-11-25",
442          "capabilities": { "tools": { "listChanged": true } },
443          "serverInfo": { "name": "Test Calculator", "version": "2.14.5" }
444        }
445      },
446      "response_is_sse": true,
447      "response_status": 200,
448      "latency_ms": 7
449    }
450  ]
451}
452```
453 
454The `transport_type` field (`"http"` or `"stdio"`) is informational. For stdio recordings, `response_is_sse` is `false` and `response_status` is `null` since there is no HTTP layer.
455 
456## CLI Reference
457 
458### `mcp-recorder record`
459 
460| Option | Default | Description |
461|---|---|---|
462| `--target` | — | URL of the real MCP server (HTTP). Mutually exclusive with `--target-stdio` |
463| `--target-stdio` | — | Command to spawn a stdio MCP server (e.g. `"node dist/index.js"`). Mutually exclusive with `--target` |
464| `--target-env` | — | Environment variable for stdio subprocess as `KEY=VALUE`. Repeatable |
465| `--port` | `5555` | Local proxy port |
466| `--output` | `recording.json` | Output cassette file path |
467| `--verbose` | — | Log full headers and bodies to stderr |
468| `--redact-server-url / --no-redact-server-url` | `true` | Strip URL path from metadata (keeps scheme + host) |
469| `--redact-env VAR` | — | Redact named env var value from metadata + responses. Repeatable |
470| `--redact-patterns REGEX` | — | Redact regex matches from metadata + responses. Repeatable |
471 
472### `mcp-recorder record-scenarios`
473 
474| Argument / Option | Default | Description |
475|---|---|---|
476| `SCENARIOS_FILE` | *(required)* | Path to YAML scenarios file |
477| `--output-dir` | `cassettes/` next to file | Output directory for cassettes |
478| `--scenario NAME` | all | Record only the named scenario(s). Repeatable |
479| `--verbose` | — | Log full request/response details to stderr |
480 
481### `mcp-recorder replay`
482 
483| Option | Default | Description |
484|---|---|---|
485| `--cassette` | *(required)* | Path to cassette file |
486| `--port` | `5555` | Local server port |
487| `--match` | `method_params` | Matching strategy (see [Matching Strategies](#matching-strategies)) |
488| `--verbose` | — | Log every matched request to stderr |
489 
490### `mcp-recorder verify`
491 
492| Option | Default | Description |
493|---|---|---|
494| `--cassette` | *(required)* | Path to golden cassette file |
495| `--target` | — | URL of the server to verify (HTTP). Mutually exclusive with `--target-stdio` |
496| `--target-stdio` | — | Command to spawn a stdio MCP server. Mutually exclusive with `--target` |
497| `--target-env` | — | Environment variable for stdio subprocess as `KEY=VALUE`. Repeatable |
498| `--ignore-fields KEY` | — | Key name to ignore at **any depth** (e.g. `timestamp`). Repeatable |
499| `--ignore-paths PATH` | — | Exact dot-path to ignore (e.g. `$.result.metadata.scrapeId`). Repeatable |
500| `--update` | — | Update the cassette with new responses (snapshot update) |
501| `--verbose` | — | Show full diff for each failing interaction |
502 
503### `mcp-recorder inspect`
504 
505| Argument | Description |
506|---|---|
507| `CASSETTE` | Path to cassette file to inspect |
508 
509## CI Integration
510 
511### GitHub Actions
512 
513Using scenarios and verify (recommended for any language):
514 
515```yaml
516steps:
517  - uses: actions/checkout@v4
518  - uses: actions/setup-python@v5
519    with:
520      python-version: "3.12"
521  - run: pip install mcp-recorder
522 
523  # Start your MCP server
524  - run: npm start &
525  - run: sleep 5
526 
527  # Verify cassettes against the live server
528  - run: |
529      mcp-recorder verify \
530        --cassette integration/cassettes/tools_and_schemas.json \
531        --target http://localhost:3000
532```
533 
534With the pytest plugin (Python projects):
535 
536```yaml
537steps:
538  - uses: actions/checkout@v4
539  - uses: actions/setup-python@v5
540    with:
541      python-version: "3.12"
542  - run: pip install mcp-recorder
543  - run: pytest
544```
545 
546Cassettes committed to the repo are replayed automatically. No server needed in CI for replay mode.
547 
548## Roadmap
549 
550- [x] `stdio` transport — subprocess wrapping for local MCP servers
551- [ ] WebSocket transport
552- [ ] `mcp-recorder diff` — compare two cassettes for breaking changes
553- [ ] TypeScript/JS cassette support — same JSON format, Vitest/Jest plugin
554 
555## Contributing
556 
557```bash
558git clone https://github.com/devhelmhq/mcp-recorder.git
559cd mcp-recorder
560uv sync --group dev
561uv run pytest
562```
563 
564## License
565 
566MIT — see [LICENSE](LICENSE) for details.
567