mockserver-monorepo Documentation

File: README.md Copy Chapter

MockServer            [](https://buildkite.com/mockserver/mockserver) [](https://github.com/mock-server/mockserver-monorepo/blob/master/LICENSE.md) [](https://github.com/mock-server/mockserver-monorepo/stargazers) [](https://artifacthub.io/packages/search?repo=mockserver) [](https://mcptoplist.com/server/com.mock-server%2Fmockserver)

MockServer is an HTTP(S) mock server and proxy for testing. It does three things:

• Mock the APIs your application depends on, so you can develop and test against systems that are unavailable, incomplete, or hard to reproduce.
• Proxy real traffic to record, inspect, and modify requests and responses in flight — and pause them at interactive proxy breakpoints to step through, edit, or abort each exchange like a debugger for network traffic.
• Chaos engineering — make dependencies misbehave on demand, injecting latency, dropped connections, and errors to test how your application copes when the systems it relies on degrade or fail.

Speaks every protocol your stack uses. HTTP/1.1 & HTTPS, HTTP/2, gRPC & gRPC-Web, WebSockets and raw TCP are auto-detected from the first bytes of each connection, so one MockServer port handles them all with no per-protocol configuration. Beyond that core: HTTP/3 (QUIC — experimental, on its own UDP port), JSON-RPC for MCP/A2A mocking, AsyncAPI-driven message-broker testing against external Kafka and MQTT brokers, and mocked AI/LLM chat-completion APIs (OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, Ollama).

Main Features Copy Section

• Mock any API — HTTP/1.1, HTTPS, HTTP/2, HTTP/3, gRPC, gRPC-Web, JSON-RPC, WebSockets, raw TCP, and message brokers (Kafka, MQTT). Match requests on method, path, query, headers, cookies and body (JSON, XML, JSONPath, XPath, regex, OpenAPI) and return configured responses.
• Proxy & record — port forwarding, web (HTTP) proxy, HTTPS tunneling (CONNECT) and SOCKS, with full visibility of even TLS-encrypted traffic.
• Dynamic responses — response templating (Velocity, Mustache, JavaScript), class/closure callbacks and webhooks.
• OpenAPI — generate expectations directly from an OpenAPI/Swagger specification.
• Verification — assert which requests were received, in what order, and how many times.
• Chaos & resilience testing — inject latency, dropped/slow connections and failures to test how your system copes with a misbehaving dependency.
• LLM / AI mocking — mock chat-completion APIs for OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI and Ollama (including streaming), plus a built-in MCP server for AI coding assistants.
• Live dashboard — watch requests, expectations and logs in real time at /mockserver/dashboard.
• Clients & integrations — Java, JavaScript/Node, Python and Ruby clients, plus JUnit and Spring support.
• Run anywhere — Docker, Helm/Kubernetes, JAR or WAR, with optional clustered state for multi-instance deployments.

See the changelog for what has shipped in each version.

Getting started in 60 seconds Copy Section

Run MockServer with Docker, then mock an endpoint and call it:

# 1. Start MockServer
docker run -d --rm -p 1080:1080 mockserver/mockserver

# 2. Mock an endpoint: GET /hello -> 200 "Hello World"
#    (MockServer exposes a REST control plane on the same port)
curl -X PUT http://localhost:1080/mockserver/expectation \
  -H 'Content-Type: application/json' \
  -d '{
        "httpRequest":  { "method": "GET", "path": "/hello" },
        "httpResponse": { "statusCode": 200, "body": "Hello World" }
      }'

# 3. Call your mock
curl http://localhost:1080/hello
# -> Hello World

…or, on macOS / Linux, install it with Homebrew and run the mockserver command directly:

brew install mockserver
mockserver run --port 1080

One-command recipes

For common end-to-end setups, the examples/docker-compose recipes are a single docker compose up each — mock from an OpenAPI spec, a record/replay proxy, a contract-validating proxy, or a chaos proxy:

cd examples/docker-compose/mock-from-openapi
docker compose up
curl http://localhost:1080/pets

The same can be done from any client library or the dashboard at http://localhost:1080/mockserver/dashboard. For more configuration options see the Docker documentation.

For every way to run MockServer yourself — Docker, docker-compose recipes, the mockserver CLI, the JVM-less binary bundle, Helm/Kubernetes, the JAR, and Testcontainers — see the Self-Hosting MockServer guide.

Drive it from Postman or Bruno

Explore MockServer's REST control plane from an API client — create expectations, verify requests, and inspect recorded traffic:

• Postman — click the button above, or import examples/postman (guide).
• Bruno (open-source, git-native) — open examples/bruno in Bruno via Open Collection (guide).

Documentation Copy Section

For usage guide please see: www.mock-server.com

Developer Documentation Copy Section

Architecture, code structure, infrastructure, and operations documentation is available in the docs/ directory.

AI Integration Copy Section

MockServer includes a built-in MCP server for AI coding assistant integration at /mockserver/mcp. See llms.txt and AI Integration docs.

Change Log Copy Section

Please see: Change Log

Community Copy Section

Requirements Copy Section

Runtime: MockServer 6.x requires Java 17+. The minimum was raised from Java 11 as part of the Jakarta EE 10 / Spring 7 platform modernisation — see the Java 17 / Jakarta upgrade guide. If you are still on Java 11, pin to the 5.15.x line (no longer receiving security updates). The official Docker image already bundles a Java 17 runtime.

Building from source: requires JDK 17+; the produced bytecode targets Java 17.

Security Note: MockServer is a development and testing tool only. See SECURITY.md for important security considerations.

Versions Copy Section

Maven Central [](https://central.sonatype.com/search?q=g:org.mock-server)

Maven Central contains the following MockServer artifacts under the org.mock-server groupId. Every artifact ships in two forms — -no-dependencies (shaded, zero transitive deps, recommended) and the plain form (transitive deps declared in the POM, for the rare case where you need to override versions yourself).

Server:

• mockserver-netty-no-dependencies / mockserver-netty — Netty-based HTTP(S) mock + proxy server (embed in tests or run standalone)
• mockserver-war — deployable WAR for hosting MockServer in a servlet container (mock mode)
• mockserver-proxy-war — deployable WAR for hosting MockServer in a servlet container (proxy mode)

Java client:

• mockserver-client-java-no-dependencies / mockserver-client-java — Java client for the MockServer REST API

Test framework integrations:

• mockserver-junit-rule-no-dependencies / mockserver-junit-rule — JUnit 4 @Rule
• mockserver-junit-jupiter-no-dependencies / mockserver-junit-jupiter — JUnit 5 extension (@MockServerSettings, @MockServerTest)
• mockserver-spring-test-listener-no-dependencies / mockserver-spring-test-listener — Spring TestExecutionListener
• mockserver-spring-boot-starter — Spring Boot auto-configuration; set mockserver.enabled=true to start MockServer and expose a MockServerClient bean (dev/test)
• mockserver-integration-testing-no-dependencies / mockserver-integration-testing — shared integration-test helpers

Build-tool plugin:

• mockserver-maven-plugin — Maven plugin to start, stop, and fork MockServer during the build lifecycle

Tip: The -no-dependencies artifacts bundle all dependencies into a single JAR with packages relocated under shaded_package.*, so they declare zero transitive dependencies. This avoids classpath conflicts with versions of Netty / Jackson / Guava / Bouncy Castle that your project already uses, and it removes the noise from CVE scanners flagging unused transitive dependencies. See the Maven Central page for full coordinates, snapshot repository setup, and the executable jar-with-dependencies form for command-line use.

6.0.0 breaking change: the <classifier>shaded</classifier> form has been removed. Replace mockserver-netty:<version>:shaded with mockserver-netty-no-dependencies:<version> (and likewise for the other shaded artifacts). The replacement produces the same shaded bytes; only the coordinates change.

SNAPSHOT builds are published to the Sonatype Central Portal snapshot repository at https://central.sonatype.com/repository/maven-snapshots/org/mock-server/.

Node Module & Grunt Plugin

NPM Registry contains the following module:

• mockserver-node - a Node.js module and Grunt plugin to start and stop MockServer
  
• mockserver-client-node - a Node.js client for both the MockServer and the proxy
  

Docker Hub

Docker Hub contains the following artifacts:

• MockServer Docker Container - a Docker container containing the Netty MockServer and proxy

Homebrew [](https://formulae.brew.sh/formula/mockserver)

MockServer is available in Homebrew (homebrew-core), the package manager for macOS and Linux:

brew install mockserver   # then run: mockserver -serverPort 1080

See the Homebrew install page and the command-line usage guide.

Helm Chart

• MockServer Helm Chart - installs MockServer into a Kubernetes cluster. The chart is published to the GitHub Container Registry as an OCI artifact (no helm repo add needed):

  bash Copy

  helm upgrade --install --create-namespace --namespace mockserver --version 7.6.0 mockserver oci://ghcr.io/mock-server/charts/mockserver

  See the Install MockServer Helm Chart guide for all versions and configuration options. A legacy .tgz is also available from www.mock-server.com.

MockServer Clients

• mockserver-client-java - a Java client for both the MockServer and the proxy (use the -no-dependencies artifact to avoid transitive dependencies)
• mockserver-client-node - a Node.js and browser client for both the MockServer and the proxy
• mockserver-client-python - a Python client for both the MockServer and the proxy
• mockserver-client-ruby - a Ruby client for both the MockServer and the proxy
• mockserver-client-go - a Go client for both the MockServer and the proxy
• mockserver-client-php - a PHP client for both the MockServer and the proxy
• mockserver-client-dotnet - a .NET client for both the MockServer and the proxy
• mockserver-client-rust - a Rust client for both the MockServer and the proxy

Community Tools

• MockServer Browser Admin - a React + TypeScript SPA for managing MockServer expectations via a web UI

Previous Versions

Issues Copy Section

If you have any problems, please check the project issues and avoid opening issues that have already been fixed. When you open an issue please provide the following information:

• MockServer version (i.e. 7.6.0)
• How your running the MockServer (i.e maven plugin, docker, etc)
• MockServer log output, at INFO level (or higher)
• What the error is
• What you are trying to do

Contributions Copy Section

Pull requests are, of course, very welcome! Please read our contributing to the project guide first. Then head over to the open issues to see what we need help with. Make sure you let us know if you intend to work on something. Also check out the project roadmap to see what is already in the backlog.

Feature Requests Copy Section

Feature requests are submitted to GitHub issues and tracked on the project roadmap.

Maintainers Copy Section

• James D Bloom

File: docs/README.md Copy Chapter

MockServer Documentation

Comprehensive internal documentation for the MockServer project covering code architecture, infrastructure, build system, CI/CD, and deployment.

Documentation style. These docs follow the Pyramid Principle with
progressive disclosure — lead with the outcome, then layer detail beneath
it. The Level column below (High / Medium / Low) is that principle applied
across the doc set: start High for the big picture, drill into Low for
subsystem detail. See .opencode/rules/documentation-style.md
for the authoring skeleton.

Documentation Index Copy Chapter

Code Architecture Copy Section

Deep-dive documentation of MockServer's codebase, from high-level module structure down to individual subsystems.

Infrastructure Copy Section

AWS accounts, CI/CD pipelines, container images, and Kubernetes deployment.

Operations Copy Section

Build process, releases, dependencies, security scanning, and the documentation website.

Plans Copy Section

Other Copy Section

Quick Reference Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Key Links Copy Chapter

• Website: https://www.mock-server.com
• GitHub: https://github.com/mock-server/mockserver-monorepo
• Docker Hub: https://hub.docker.com/r/mockserver/mockserver
• Maven Central: org.mock-server:mockserver-netty
• Helm Chart Repo: https://www.mock-server.com/mockserver-7.6.0.tgz
• SwaggerHub API: https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi
• Buildkite: https://buildkite.com/mockserver/mockserver
• Snyk: https://app.snyk.io/org/mockserver/projects