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

mcp-mock is most useful when you want a predictable MCP server for local development, test automation, or demos. You can either run it from the command line with a schema file or create a server directly in Python.

CLI usage

The CLI entry point is mcp-mock serve. It reads a JSON file that describes the tools you want to expose and starts a mock MCP server over stdio.

Run a server from a schema file:

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

Add simulated latency and failure injection:

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

CLI options

• --schema or -s: required path to a JSON schema file
• --latency: adds a delay in milliseconds before each tool response
• --error-rate: injects failures probabilistically, from 0.0 to 1.0

Python API usage

You can also create a server programmatically in Python.

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()

This example does the following:

• creates a mock server named DemoServer
• attaches a chaos configuration with 50ms latency and a 5% error rate
• registers a tool called get_user
• starts the server over stdio

Registering custom handlers

If you want more control than the built-in synthetic responses, you can provide a custom handler when registering a tool.

from mcp_mock.server import MockMCPServer

server = MockMCPServer(name="DemoServer")

async def get_user_handler(user_id: str):
    return {"id": user_id, "name": "Ada Lovelace"}

server.register_tool(
    name="get_user",
    description="Return a user record",
    handler=get_user_handler,
)

Schema file format

A schema file should contain a top-level object with a server name and a list of tools. A simple example is shown below:

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

You can expand this format with additional metadata if you want to describe more complex tools, but the current implementation focuses on simple tool registration and synthetic responses.

When to use mcp-mock

Use mcp-mock when you want to:

• test MCP integrations locally without a real backend
• simulate slow or flaky tool responses
• create demos with predictable tool outputs
• validate client behavior under latency and injected errors

Development

Run the test suite:

pytest -q

License

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