mock-mcp

Mock MCP Server - AI-generated mock data based on your OpenAPI JSON Schema definitions. The project uses a Daemon + Adapter architecture that enables multiple MCP clients (Cursor, Claude Desktop, etc.) to run simultaneously without port conflicts, while providing robust claim-based concurrency control for mock batch processing.

Table of Contents

• Quick Start
• Why Mock MCP
• What Mock MCP Does
• Architecture
• Configure MCP Server
• Connect From Tests
• Describe Requests with Metadata
• MCP Tools
• CLI Commands
• Available APIs
• Environment Variables
• How It Works
• Use the development scripts
• License

Quick Start

1. Install the package. Add mock-mcp as a dev dependency inside your project.

npm install -D mock-mcp
# or
yarn add -D mock-mcp
# or
pnpm add -D mock-mcp

2. Configure the Model Context Protocol server. Add mock-mcp to your MCP client configuration (Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "mock-mcp": {
      "command": "npx",
      "args": ["-y", "mock-mcp@latest", "adapter"]
    }
  }
}

Note: The adapter command connects to a shared daemon process that is automatically started when needed. This eliminates port conflicts when running multiple MCP clients simultaneously.

3. Connect from your tests. Use connect to retrieve a mock client and request data for intercepted calls.

import { render, screen, fireEvent } from "@testing-library/react";
import { connect } from "mock-mcp";

const userSchema = {
  summary: "Fetch the current user",
  response: {
    type: "object",
    required: ["id", "name"],
    properties: {
      id: { type: "number" },
      name: { type: "string" },
    },
  },
};

it("example", async () => {
  const mockClient = await connect();
  const metadata = {
    schemaUrl: "https://example.com/openapi.json#/paths/~1user/get",
    schema: userSchema,
    instructions: "Respond with a single user described by the schema.",
  };

  fetchMock.get("/user", async () => {
    const response = await mockClient.requestMock("/user", "GET", { metadata }) // add mock via mock-mcp
    return response.data
  });

  const result = await fetch("/user");
  const data = await result.json();
  expect(data).toEqual({ id: 1, name: "Jane" });
}, 10 * 60 * 1000); // 10 minute timeout for AI interaction

4. Run with MCP enabled. Prompt your AI client to run the persistent test command and provide mocks through the tools.