mcp-mock

mcp-mock is a lightweight synthetic mock server for the Model Context Protocol (MCP). It is designed for local testing, demos, and resilience experiments where you want a predictable MCP endpoint without depending on a real backend.

The current codebase includes:

• a MockMCPServer implementation for registering tools and serving responses
• a synthetic response generator powered by Faker
• a chaos layer for latency and injected failures
• a CLI entry point for running a mock server from a schema file
• a pytest suite covering the core behaviors

Project layout

mcp-mock/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── mcp_mock/
│       ├── __init__.py
│       ├── chaos.py
│       ├── cli.py
│       ├── generator.py
│       └── server.py
└── tests/
    ├── test_chaos.py
    ├── test_cli.py
    ├── test_generator.py
    └── test_server.py

Installation

Install the package from the project root:

python -m pip install -e .

Install development dependencies as well:

python -m pip install -e ".[dev]"

Usage

CLI

Run a mock server from a JSON schema file:

mcp-mock serve --schema ./tools_schema.json

Add chaos behavior:

mcp-mock serve --schema ./tools_schema.json --latency 100 --error-rate 0.1

Python API

from mcp_mock.chaos import ChaosConfig
from mcp_mock.server import MockMCPServer

chaos = ChaosConfig(latency_ms=50, error_rate=0.05)
server = MockMCPServer(name="DemoServer", chaos=chaos)
server.register_tool(name="get_user", description="Get a user")
server.run_stdio()

Schema file format

A simple schema file can look like this:

{
  "name": "ToolServer",
  "tools": [
    {
      "name": "get_user",
      "description": "Get a user by ID"
    },
    {
      "name": "execute_sql",
      "description": "Execute a SQL query"
    }
  ]
}

Development

Run the test suite:

pytest -q

License

This project is licensed under the MIT License. See LICENSE for details.