Skip to main content
Glama
mcp-mock-server

mcp-mock-server

by shriramkv

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.

Related MCP server: Mock MCP Server

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.

Available Tools

1 tool
echoB

Echo back the provided message.

Inputs: message (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusion between tools. The purpose of echoing a message is unambiguous.

    Naming Consistency5/5

    The single tool name 'echo' is clear and directly describes its function. With only one tool, naming consistency is trivially satisfied.

    Tool Count1/5

    The server provides only a single trivial echo tool, which is an extreme mismatch for any meaningful purpose. A server with one trivial tool earns a score of 1.

    Completeness1/5

    The tool surface is severely incomplete; an echo tool alone provides no meaningful coverage of any domain. There are no additional operations to support a workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A simple demonstration MCP server that provides an echo tool and resource for learning how to build MCP servers. Serves as a starting point and template for creating custom MCP server implementations.
      1
      -
    • A
      license
      B
      quality
      D
      maintenance
      A mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A minimal local HTTP MCP mock server for development and testing, providing predictable tool responses with OAuth token support and zero dependencies.
      -