MCP server for James Bloom MockServer - create expectations, verify requests, and manage mock state
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.
You need a running MockServer instance:
# Using Docker (easiest)
docker run -d -p 1080:1080 mockserver/mockserver
npx mockserver-mcp
npm install -g mockserver-mcp
mockserver-mcp
| Variable | Description | Default |
|---|---|---|
MOCKSERVER_HOST | MockServer hostname | localhost |
MOCKSERVER_PORT | MockServer port | 1080 |
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.
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 matchqueryStringParameters: Query parameters to matchheaders: Headers to matchbody: Body matcher with type (STRING, JSON, REGEX, XPATH, JSON_PATH) and valuehttpResponse: Response configuration
statusCode: HTTP status codeheaders: Response headersbody: Response body (string or object)delay: Response delay with timeUnit and valuetimes: How many times to match (remainingTimes, unlimited)timeToLive: Expectation lifetime (timeUnit, timeToLive)Example:
{
"httpRequest": {
"method": "GET",
"path": "/api/users"
},
"httpResponse": {
"statusCode": 200,
"body": { "users": [] }
}
}
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 requestsatMost: Maximum number of requestsexactly: Exact number of requestsExample:
{
"httpRequest": {
"method": "POST",
"path": "/api/orders"
},
"times": {
"atLeast": 1
}
}
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"
}
}
Perform a full reset of MockServer, clearing all expectations and recorded requests.
Parameters: None
Retrieve recorded requests from MockServer.
Parameters:
httpRequest (optional): Request matcher to filter recorded requestsExample:
{
"httpRequest": {
"method": "GET"
}
}
Get MockServer connection status and configuration.
Parameters: None
API mocking enables early testing — start building and testing your frontend or integrations before the backend is ready. No more waiting. Ship faster.
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y mockserver-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-akkshay10-mcpclientmock": {
"command": "npx",
"args": [
"-y",
"mockserver-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencemockserver-mcpnpmio.github.Akkshay10/MCPClientMock works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.