<div align="center">

mcp-vcr

VCR for MCP servers: record and replay AI agent tool calls to test agentic workflows without side-effects or rate limits.

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

🎯 Why?

Developers building AI agents with MCP servers struggle to test workflows that trigger side-effects (sending emails, creating tickets) or hit API rate limits during debugging loops. While VCR-style recording exists for HTTP, there is no lightweight, zero-dependency stdio proxy to record and replay JSON-RPC MCP traffic locally.

Target audience: AI agent developers, MCP server authors, and QA engineers who need deterministic, offline testing for agentic workflows.

✨ Features

• ✨ Record MCP stdio traffic to a local JSON cassette file
• ✨ Replay saved tool calls deterministically without spawning the upstream server
• ✨ Zero-dependency, transparent stdio proxy that works with any MCP client (Claude Desktop, Cursor, etc.)

🚀 Quick Start

# Install
pip install mcp-vcr

# Run
mcp-vcr --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/mcp-vcr.git
cd mcp-vcr

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
mcp-vcr --help

# Common usage examples
mcp-vcr --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.

---

<div align="center">

If this project helped you, please ⭐ star it!

Made with ❤️ and AI

</div>