com.mock-server/mockserver

MockServer

MockServer mocks, records, and chaos-tests any HTTP(S) dependency your application talks to — one binary, no per-protocol setup.

Why MockServer

• One port, every protocol — HTTP/1.1, HTTPS, HTTP/2, gRPC & gRPC-Web, WebSockets and raw TCP are auto-detected from the first bytes of each connection. Beyond that: HTTP/3 (QUIC, experimental), JSON-RPC for MCP/A2A mocking, and AsyncAPI-driven testing against Kafka/MQTT brokers.
• Mock, proxy, or both — return canned/templated/callback responses, or sit as a proxy (port forwarding, HTTP proxy, HTTPS tunneling, SOCKS) and record, inspect, and modify real traffic in flight, with full visibility into TLS-encrypted exchanges.
• Chaos engineering built in — inject latency, dropped connections, and errors on demand to see how your application copes when a dependency misbehaves.
• Mock AI too — chat-completion APIs for OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI and Ollama (including streaming), plus a built-in MCP server so AI coding assistants can drive MockServer directly.
• Generate mocks, don't hand-write them — from an OpenAPI/Swagger spec, with request matching on method, path, query, headers, cookies, and body (JSON, XML, JSONPath, XPath, regex).
• Fits your stack — Java, JavaScript/Node, Python, Ruby, Go, .NET, Rust, and PHP clients, plus JUnit and Spring support; runs as Docker, Helm/Kubernetes, a JAR, or a WAR, with a live dashboard and optional clustered state for multi-instance deployments.

See the changelog for what shipped in each version.

Getting started in 60 seconds

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 with Homebrew and run the mockserver command directly:

brew install mockserver
mockserver run --port 1080

For every way to run MockServer — Docker, docker-compose recipes, the mockserver CLI, a JVM-less binary bundle, Helm/Kubernetes, the JAR, and Testcontainers — see the Self-Hosting MockServer guide. The same setup can be driven from any client library or the dashboard at http://localhost:1080/mockserver/dashboard.

One-command recipes

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

Drive it from Postman or Bruno

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

Install

Client libraries (create expectations, verify requests, drive the control plane from your tests):

Full install options (SNAPSHOT repository, WAR deployment, Testcontainers modules, package-manager channels) are on the Self-Hosting guide and Where to find MockServer.

Requirements

Runtime: Java 17+ (raised from Java 11 in MockServer 6.0.0 — see the Java 17 / Jakarta upgrade guide; pin to 5.15.x if you need Java 11). The official Docker image bundles its own JVM, so containerised users need no JVM of their own.

Building from source: JDK 17+.

Security note: MockServer is a development and testing tool only — see SECURITY.md.

Documentation

• Usage guide: www.mock-server.com
• Architecture, code structure, infrastructure, and operations docs: docs/
• AI/MCP integration: built-in MCP server at /mockserver/mcp — see llms.txt and the AI Integration docs

Versions

• What changed: changelog and GitHub releases (every version is also a git tag mockserver-<version>).
• API docs for a version: Java API at https://mock-server.com/versions/<version>/apidocs/index.html; REST API on SwaggerHub (one spec per major.minor.x).
• Java 11: the last Java 11-compatible release is 5.15.0 (January 2023).

6.0.0 breaking change: the <classifier>shaded</classifier> Maven form was removed. Replace mockserver-netty:<version>:shaded with mockserver-netty-no-dependencies:<version> (same shaded bytes, new coordinates).

Community & Contributing

• Issues / bugs / feature requests: GitHub Issues — please include your MockServer version, how you're running it (Docker, Maven plugin, etc.), and INFO-level (or higher) log output.
• Discussions: GitHub Discussions
• Roadmap: GitHub Project
• Security policy: SECURITY.md
• Community tools: MockServer Browser Admin, a React + TypeScript web UI for managing expectations
• Contributing: pull requests are very welcome — read CONTRIBUTING.md first, then check the open issues and let us know if you intend to work on something.

Maintainers

• James D Bloom