home / mcp / mockserver mcp server

Mockserver MCP Server

Provides an MCP interface to control a MockServer instance for creating, verifying, and clearing mock HTTP interactions.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can manage a MockServer instance through this MCP server, enabling you to create mock expectations, verify requests, clear state, and run MockServer programmatically from your MCP client. This streamlines testing workflows by letting you define and validate HTTP interactions from automation or AI-assisted tools.

How to use

You will start the MCP server and connect your MCP client to it. From there you can create expectations that describe how MockServer should respond to incoming requests, verify that certain requests were received, retrieve recorded requests, and reset or clear data as needed. Use the MCP endpoints to drive MockServer behavior in end-to-end tests, integration tests, or frontend–backend mock scenarios.

How to install

Prerequisites: you need a running MockServer instance and Node.js installed on your machine.

# Run a MockServer instance using Docker (easiest)
docker run -d -p 1080:1080 mockserver/mockserver

# Install the MCP server client globally (optional)
npm install -g mockserver-mcp

Configuration and startup

You start the MCP server using either of these commands. Both connect to a local MockServer running on port 1080 by default. If you run MockServer on a different host or port, adjust the host and port values accordingly.

# Start using npx (recommended)
npx mockserver-mcp

# Or start via a globally installed CLI
mockserver-mcp

Additional configuration notes

Environment variables you may set to point clients to your MockServer instance are shown below. Set MOCKSERVER_HOST to the hostname or IP where MockServer runs and MOCKSERVER_PORT to its port. For shared team deployments, point to the appropriate server address.

# Example environment configuration for MCP client
MOCKSERVER_HOST=localhost
MOCKSERVER_PORT=1080

Security and usage tips

Keep your MockServer endpoints private in test environments and avoid exposing internal mocks publicly. Use clear, scoped expectations and regularly clear or reset state between test suites to prevent cross-test contamination.

Troubleshooting

If the MCP server cannot connect to MockServer, verify that MockServer is reachable at the configured host and port and that nothing is blocking the connection. Check firewall rules, Docker networking, or host network configurations if you run MockServer in a container.

Available tools

mockserver_create_expectation

Create a mock HTTP expectation in MockServer by defining an httpRequest matcher and a corresponding httpResponse.

mockserver_verify

Verify that requests matching given criteria were received by MockServer, with configurable times constraints.

mockserver_clear

Clear specific expectations or all stored expectations and recorded requests from MockServer.

mockserver_reset

Perform a full reset of MockServer, clearing all data and state.

mockserver_retrieve_requests

Retrieve the list of recorded requests from MockServer, optionally filtered by httpRequest criteria.

mockserver_status

Check the connection status and current configuration of the MockServer setup.