mcpField
M
MCPClientMock

MCPClientMock

Local
github.com/Akkshay10Developer Tools1Updated 45w ago
Repository

About MCPClientMock

MCP server for controlling James Bloom MockServer from AI assistants and test workflows. It provides tools to define HTTP expectations, inspect and verify requests, and manage server state.

Key features

  1. 01Create HTTP expectations
  2. 02Match requests by method, path, headers, query, or body
  3. 03Verify received request counts
  4. 04Retrieve recorded requests
  5. 05Clear or reset MockServer state
  6. 06Check connection status

Use cases

  1. 01Mock an API while its backend is still in development
  2. 02Verify that an integration sent expected HTTP requests
  3. 03Inspect recorded traffic during tests

MCP support

Exposes MockServer expectation creation, request verification and retrieval, state management, and status as tools for MCP clients. It connects to a running MockServer instance.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "akkshay10-mcpclientmock": {
      "command": "npx",
      "args": [
        "-y",
        "mockserver-mcp"
      ],
      "env": {
        "MOCKSERVER_HOST": "<MOCKSERVER_HOST>",
        "MOCKSERVER_PORT": "<MOCKSERVER_PORT>"
      }
    }
  }
}
Run commandnpx -y mockserver-mcp
Environment variables to set
MOCKSERVER_HOSTMockServer hostname
MOCKSERVER_PORTMockServer port

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmmockserver-mcp1.0.2

Tools

6

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
idstringNoOptional expectation identifier
timesobjectNoHow many times this expectation should be matched
times.unlimitedbooleanNo
times.remainingTimesnumberNo
timeToLiveobjectNoHow long this expectation should remain active
timeToLive.timeUnitenumNoMILLISECONDS | SECONDS | MINUTES
timeToLive.timeToLivenumberNo
httpRequestobjectYesRequest matching criteria (method, path, headers, body, etc.)
httpRequest.bodyobjectNoBody matcher configuration
httpRequest.body.typeenumNoSTRING | JSON | REGEX | XPATH | JSON_PATH
httpRequest.body.valuestringNo
httpRequest.body.matchTypeenumNoSTRICT | ONLY_MATCHING_FIELDS
httpRequest.pathstringNoURL path to match
httpRequest.methodstringNoHTTP method to match (GET, POST, PUT, DELETE, etc.)
httpRequest.headersobjectNoHeaders to match
httpRequest.pathParametersobjectNoPath parameters to match
httpRequest.queryStringParametersobjectNoQuery string parameters to match
httpResponseobjectNoResponse configuration
httpResponse.bodyanyNoResponse body (string or object)
httpResponse.delayobjectNoResponse delay configuration
httpResponse.delay.valuenumberNo
httpResponse.delay.timeUnitenumNoMILLISECONDS | SECONDS
httpResponse.headersobjectNoResponse headers
httpResponse.statusCodenumberNoHTTP status code to return

Details

From the project README

mockserver-mcp

An MCP (Model Context Protocol) server for interacting with James Bloom's MockServer. This enables AI assistants to create mock HTTP expectations, verify requests, clear state, and manage MockServer instances programmatically.

Prerequisites

You need a running MockServer instance:

# Using Docker (easiest)
docker run -d -p 1080:1080 mockserver/mockserver

Installation

Using npx (recommended)
npx mockserver-mcp
Global installation
npm install -g mockserver-mcp
mockserver-mcp

Configuration

Environment Variables
VariableDescriptionDefault
MOCKSERVER_HOSTMockServer hostnamelocalhost
MOCKSERVER_PORTMockServer port1080
MCP Client Configuration

Add to your MCP client configuration file (e.g., Claude Desktop, Kiro, Cursor):

{
  "mcpServers": {
    "mockserver": {
      "command": "npx",
      "args": ["-y", "mockserver-mcp"],
      "env": {
        "MOCKSERVER_HOST": "localhost",
        "MOCKSERVER_PORT": "1080"
      }
    }
  }
}

For shared team MockServer, change MOCKSERVER_HOST to your server's address.

Available Tools

mockserver_create_expectation

Create a mock HTTP expectation on MockServer.

Parameters:

  • httpRequest (required): Request matching criteria
    • method: HTTP method (GET, POST, PUT, DELETE, etc.)
    • path: URL path to match
    • queryStringParameters: Query parameters to match
    • headers: Headers to match
    • body: Body matcher with type (STRING, JSON, REGEX, XPATH, JSON_PATH) and value
  • httpResponse: Response configuration
    • statusCode: HTTP status code
    • headers: Response headers
    • body: Response body (string or object)
    • delay: Response delay with timeUnit and value
  • times: How many times to match (remainingTimes, unlimited)
  • timeToLive: Expectation lifetime (timeUnit, timeToLive)

Example:

{
  "httpRequest": {
    "method": "GET",
    "path": "/api/users"
  },
  "httpResponse": {
    "statusCode": 200,
    "body": { "users": [] }
  }
}
mockserver_verify

Verify that requests matching criteria were received by MockServer.

Parameters:

  • httpRequest (required): Request matching criteria (same as create_expectation)
  • times: Expected request count
    • atLeast: Minimum number of requests
    • atMost: Maximum number of requests
    • exactly: Exact number of requests

Example:

{
  "httpRequest": {
    "method": "POST",
    "path": "/api/orders"
  },
  "times": {
    "atLeast": 1
  }
}
mockserver_clear

Clear expectations and recorded requests from MockServer.

Parameters:

  • httpRequest (optional): Request matcher to clear specific expectations. If not provided, clears all.

Example:

{
  "httpRequest": {
    "path": "/api/users"
  }
}
mockserver_reset

Perform a full reset of MockServer, clearing all expectations and recorded requests.

Parameters: None

mockserver_retrieve_requests

Retrieve recorded requests from MockServer.

Parameters:

  • httpRequest (optional): Request matcher to filter recorded requests

Example:

{
  "httpRequest": {
    "method": "GET"
  }
}
mockserver_status

Get MockServer connection status and configuration.

Parameters: None

Why Mocking?

API mocking enables early testing — start building and testing your frontend or integrations before the backend is ready. No more waiting. Ship faster.

Requirements

  • Node.js >= 18.0.0
  • A running MockServer instance

Links

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.