MockServer mocks, records, and chaos-tests any HTTP(S) dependency your application talks to — one binary, no per-protocol setup.
- 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.
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 1080For 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.
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
- Postman — click the button above, or import
examples/postman(guide). - Bruno (open-source, git-native) — open
examples/brunoin Bruno via Open Collection (guide).
| Channel | Command |
|---|---|
| Docker | docker run -d --rm -p 1080:1080 mockserver/mockserver |
| Docker from GitHub Container Registry (avoids Docker Hub's pull limit) | docker run -d --rm -p 1080:1080 ghcr.io/mock-server/mockserver |
| Homebrew (macOS/Linux) | brew install mockserver |
| Helm (chart guide) | helm upgrade --install --namespace mockserver mockserver oci://ghcr.io/mock-server/charts/mockserver |
Maven Central  |
org.mock-server:mockserver-netty-no-dependencies — see all Maven artifacts (server, WARs, JUnit 4/5, Spring, Maven plugin) |
| npm | mockserver-node (start/stop) |
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.
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.
- 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
- 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 permajor.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. Replacemockserver-netty:<version>:shadedwithmockserver-netty-no-dependencies:<version>(same shaded bytes, new coordinates).
- 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.