mcp-mock-server

A zero-dependency, configurable mock MCP server for testing MCP clients and harnesses.

When you build an MCP client, an agent, or a testing tool, you need a server to point it at. Spinning up a real one (with real credentials and side effects) just to check that your client speaks the protocol correctly is heavy and flaky. mcp-mock-server is a tiny stand-in: describe your tools and their canned responses in a JSON file, and it serves a correct MCP handshake over stdio.

Part of the AAIF (Agentic AI Innovation Foundation) open-source toolset for the agentic AI ecosystem. It pairs naturally with MCP conformance, audit, and load-testing tools: use the mock as the target while you test the tester.

Highlights

• Speaks JSON-RPC 2.0 over stdio: initialize, notifications/initialized, ping, tools/list, tools/call.
• Tools, schemas, and responses are fully driven by a JSON config.
• Simulates error responses and missing-argument handling for testing sad paths.
• Simple {argument} templating in responses.
• Standard library only. No pip dependencies.

Install

pip install -e .

Requires Python 3.9 or newer.

Quick start

Serve the built-in echo tool:

mcp-mock-server

Print the default config to use as a starting point:

mcp-mock-server --print-default-config > my-tools.json

Serve your own tools:

mcp-mock-server --config examples/weather.json

Config format

{
  "name": "weather-mock",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_forecast",
      "description": "Return a canned weather forecast for a city.",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "response": { "text": "Forecast for {city}: 30C, clear skies." }
    }
  ]
}

• inputSchema is standard JSON Schema. Listed required fields are enforced.
• response.text supports {argument} templating from the call arguments.
• Set response.isError to true to simulate a tool that fails.
• If response.text is omitted, the server echoes the arguments back.

Try it by hand

Send a request on stdin (each message is one JSON line):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"hello"}}}' \
  | mcp-mock-server

Wiring into an MCP client

Most clients accept a command to launch a server. Point them at:

{
  "mcpServers": {
    "mock": { "command": "mcp-mock-server", "args": ["--config", "my-tools.json"] }
  }
}

Development

pip install -e .
pytest

License

MIT. See LICENSE.