mcpmock

mcpmock is a Bun + TypeScript playground for rapidly prototyping MCP servers using a single YAML configuration. You describe your mock MCP server in a YAML file, then run the CLI, which starts either a stdio-based server for agent integrations or an HTTP server for browser/HTTP interactions. The tools defined in your YAML respond with configured data, with optional templating to interpolate tool inputs into responses. This makes it easy to test tool shapes, response formats, and transport behaviors without building full backend logic. The CLI can operate in two transports: stdio (default) for close integration with agents via stdin/stdout, and http which spins up an Express server backed by StreamableHTTPServerTransport for web-based interactions. Cross-origin requests are enabled so MCP Inspector and similar tools can connect directly.

Prerequisites:

• Node.js and npm installed, or Bun for local development workflow (bun install).
• Access to the npm registry to install mcpmock globally or locally.

Option A: Install globally (recommended for quick usage)

1. Install the package globally:

npm install -g mcpmock

2. Run the CLI pointing to your YAML config, for example:

npx mcpmock ./examples/basic/mock.yaml

Option B: Install locally and run from source (development workflow)

1. Install dependencies (bun preferred for speed):

bun install

2. Build the project (if you’re developing locally):

bun run build

3. Run the server using the built bundle (example YAML path):

node dist/index.js examples/basic/mock.yaml

Notes:

• The CLI expects a YAML file that defines server, tools, and responses (as shown in the README examples).
• When using the http transport, the server will start an Express server and expose endpoints suitable for MCP tooling.

Tips and known considerations:

• Ensure each tool in your YAML config has a unique name and a valid input_schema. The response can reference args via {{ args.* }} and supports nested structures.
• If a referenced argument is missing, the tool call will error, which helps with debugging during iteration.
• The stdio transport is ideal for integration with agents via streams, while the http transport is useful for browser-based testing and MCP Inspector workflows.
• Cross-origin requests are allowed with MCP Session IDs exposed to enable seamless agent/browser interactions.
• When developing locally, you can use Bun to speed up the build and testing process, but npm can be used as well for broader compatibility.