<div align="center">

# `mcp-mock`

### Spin up deterministic mock MCP servers from a JSON fixture file for agent and client testing.

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) ![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![MCP](https://img.shields.io/badge/MCP-mock-orange)

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

</div>

---

## 🎯 Why?

Trending repos show a wave of MCP gateways, agent harnesses, and CLI clients, but testing tooling is still primitive. Developers need deterministic offline MCP servers to validate clients and agent tool use without hitting real APIs. Existing MCP examples are SDK snippets, not a fixture-driven mock server with CLI ergonomics.

**Target audience:** Developers building MCP clients, agent harnesses, and CI pipelines who need reproducible offline tool endpoints.

## ✨ Features

- ✨ **JSON fixture specs for MCP tools**
- ✨ **stdio JSON-RPC server supporting initialize, tools/list, and tools/call**
- ✨ **canned results, tool-level errors, latency simulation, and {{argument}} templating**
- ✨ **CLI commands to init, validate, list, run, and call mock tools**

## 🚀 Quick Start

```bash
# Install
pip install mcp-mock

# Run
mcp-mock --help
```

## 📦 Installation

### From Source

```bash
git clone https://github.com/YOUR_USERNAME/mcp-mock.git
cd mcp-mock
```

```bash
# 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](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
mcp-mock --help

# Common usage examples
mcp-mock --example
```

## 🏗️ Architecture

```mermaid
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](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>