# MockServer: one port for HTTP, gRPC, WebSockets and Kafka mocks

> MockServer is an Apache-2.0 Java mock server and proxy that auto-detects HTTP/1.1, HTTP/2, gRPC, WebSockets and raw TCP on a single port. It is powerful for polyglot stacks, but the JVM heritage shows in the setup.

**mock-server/mockserver-monorepo** — MockServer is an HTTP(S) mock server and proxy for testing that lets you mock APIs, inspect and modify live traffic, and inject failures. It supports HTTP/1.1, HTTP/2, gRPC, WebSockets, TCP and more on a single port, with additional support for HTTP/3, message brokers, and AI/LLM APIs.

- Repository: https://github.com/mock-server/mockserver-monorepo
- Website: https://www.mock-server.com
- Stars: 4,976 · Forks: 1,116
- Language: Java
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/mock-server-mockserver-monorepo

## The polyglot protocol problem MockServer targets

Most mocking tools assume HTTP. That assumption breaks the moment a service under test talks gRPC to one dependency, opens a WebSocket to another, and pushes a Kafka message to a third. Teams then run three stub servers, three configuration formats and three sets of ports, and the test environment becomes harder to reason about than the code.

MockServer's answer is a single port. The README states that HTTP/1.1 and HTTPS, HTTP/2, gRPC and gRPC-Web, WebSockets and raw TCP are auto-detected from the first bytes of each connection, with no per-protocol configuration. HTTP/3 (QUIC) is described as experimental and runs on its own UDP port. Beyond that core, the project lists JSON-RPC for MCP and A2A mocking, AsyncAPI-driven message-broker testing against external Kafka and MQTT brokers, and mocked chat-completion APIs for OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI and Ollama.

The intended user is a test or platform engineer maintaining a shared environment for several services, not someone who needs one stubbed endpoint for a unit test. That distinction matters because the same flexibility that removes three stub servers also removes the simplicity that made them easy to debug.

## Expectations, matching and the control plane on port 1080

The mechanism is expectation-based. You send a request definition to the REST control plane, and MockServer stores it and matches incoming traffic against it. Matching can be done on method, path, query, headers, cookies and body, with body matchers for JSON, XML, JSONPath, XPath, regex and OpenAPI. When a request matches, the configured response is returned.

Responses are not static. The README lists response templating with Velocity, Mustache and JavaScript, plus class and closure callbacks and webhooks. That means a mock can compute a value, echo part of the request, or call out to something else before replying. Verification is the other half: you can assert which requests were received, in what order, and how many times.

The proxy mode reuses the same machinery on live traffic. MockServer supports port forwarding, a web HTTP proxy, HTTPS tunneling via CONNECT, and SOCKS, with visibility into TLS-encrypted traffic. The README describes pausing exchanges at interactive proxy breakpoints to step through, edit, or abort each one, which is closer to a debugger than to a stub. A live dashboard at /mockserver/dashboard shows requests, expectations and logs in real time.

## Running MockServer with Docker and creating a first expectation

The README's quickstart uses Docker. The container listens on port 1080, and the control plane shares that port with the mocked endpoints.

```bash
docker run -d --rm -p 1080:1080 mockserver/mockserver
```

With the container running, create an expectation with a PUT to /mockserver/expectation. The request body describes the match and the response.

```bash
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" }
      }'
```

Calling the mocked path should return the configured body.

```bash
curl http://localhost:1080/hello
```

On macOS or Linux the README also documents a Homebrew route, which runs the server as a local command rather than a container.

```bash
brew install mockserver
mockserver run --port 1080
```

For end-to-end setups, the repository ships docker-compose recipes under examples/docker-compose, described as one docker compose up each: mock from an OpenAPI spec, a record/replay proxy, a contract-validating proxy, and a chaos proxy. The OpenAPI recipe is invoked as follows.

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

The README points to a Self-Hosting guide for the full list of deployment options: Docker, docker-compose recipes, the mockserver CLI, a JVM-less binary bundle, Helm and Kubernetes, the JAR, and Testcontainers.

## Where MockServer is the wrong tool

The most obvious mismatch is scope. If your tests only need HTTP stubs and your team has no JVM in the build, you are paying for protocol coverage you will not use. MockServer is a Java project, and the repository is a monorepo containing mockserver-core, mockserver-client-node, mockserver-node, mockserver-testcontainers, mockserver-ui and a Helm chart, among other modules. That structure is a strength for contributors and a surface area for anyone who just wants a binary.

The second limitation is that the documentation does not cover every operational question. The README does not document rollback of expectations, nor does it describe what happens when two expectations overlap in specificity. Expectation ordering and priority are the kind of detail that decides whether a shared mock environment behaves predictably, and the README is silent on it. The changelog and the linked documentation site are where that would live, and a reader should check there rather than assume.

Third, HTTP/3 is labelled experimental and bound to a separate UDP port, so it does not inherit the single-port story that applies to the other protocols. Anyone planning QUIC coverage should treat that as a preview rather than a supported path.

Finally, a proxy that can see inside TLS and pause live traffic is a security-sensitive component. The README does not discuss how the dashboard or control plane are protected in a shared environment, and the repository does include a SECURITY.md, so that file is the place to look before exposing port 1080 beyond localhost.

## MockServer versus WireMock and Mockoon

WireMock is the closest comparison, and the difference is protocol breadth. WireMock is also a JVM-based HTTP mock server, and the related searches show people comparing the two directly. MockServer's distinguishing claim is that HTTP/2, gRPC, gRPC-Web, WebSockets and raw TCP are auto-detected on the same port as HTTP, with message-broker testing against Kafka and MQTT layered on top. If your system under test is HTTP-only, that breadth buys nothing, and WireMock's narrower surface may be easier to operate.

Mockoon sits at the other end of the spectrum. It is a desktop-oriented mocking tool, and the search data shows people asking what it is used for. The trade-off is the inverse of MockServer's: less infrastructure, less protocol coverage, and a different model for sharing mocks across a team. MockServer's answer to sharing is the REST control plane plus clustered state for multi-instance deployments, which the README lists as an option.

The practical split is this. Choose MockServer when the protocol mix is the problem. Choose a lighter HTTP-only tool when the protocol mix is not the problem and the JVM is.

## Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-09, which is recent. Releases are frequent: mockserver-7.6.0 on 2026-08-17, mockserver-7.5.0 on 2026-07-29, and mockserver-7.4.0 on 2026-07-04. That cadence cuts both ways. It means fixes arrive quickly, and it means a pinned version drifts out of date within weeks. The changelog is the file to read before upgrading, since the README points to it for what has shipped in each version.

The upgrade cost depends on how you deploy. A Docker image tag or a Helm chart value is a one-line change. A JAR embedded in a Java test suite is a dependency bump with the usual transitive risk. The monorepo layout means client libraries for .NET, Go, Node, PHP, Python, Ruby and Rust live alongside the Java core, so a server upgrade and a client upgrade are separate decisions even though they ship from one repository.

The licence is Apache-2.0, which permits commercial use and modification with the usual attribution and notice requirements. That is a permissive licence, but it is not legal advice, and anyone embedding MockServer in a distributed product should read LICENSE.md in the repository rather than rely on the licence identifier alone.

## Conclusion

Adopt MockServer if you need one process to mock HTTP, gRPC, WebSockets and raw TCP, or if you want to record and rewrite live traffic at proxy breakpoints. Skip it if your tests only need HTTP stubs and you would rather avoid a JVM toolchain: WireMock or Mockoon will be lighter. Before committing, verify the protocol auto-detection on your own traffic, check that your JDK or Docker image matches what the self-hosting guide recommends, and confirm which client libraries ship for your language, since the repository lists .NET, Go, Node, PHP, Python, Ruby and Rust clients alongside the Java one.

## FAQ

### What is MockServer?

MockServer is an HTTP and HTTPS mock server and proxy for testing. It mocks APIs your application depends on, proxies real traffic so you can record, inspect and modify requests and responses, and inject failures for chaos engineering.

### What is the purpose of a mock API?

A mock API lets you develop and test against systems that are unavailable, incomplete, or hard to reproduce, according to the README. MockServer also lets you verify which requests were received, in what order, and how many times.

### How do I run MockServer with Docker?

The README gives a one-line command: docker run -d --rm -p 1080:1080 mockserver/mockserver. The control plane shares port 1080 with the mocked endpoints, so you create expectations by sending a PUT to /mockserver/expectation on the same port.

### Which protocols does MockServer support on one port?

The README states that HTTP/1.1 and HTTPS, HTTP/2, gRPC and gRPC-Web, WebSockets and raw TCP are auto-detected from the first bytes of each connection, with no per-protocol configuration. HTTP/3 runs on its own UDP port and is described as experimental.

### Is MockServer free to use?

The repository is licensed under Apache-2.0, which permits commercial use and modification subject to the licence's notice requirements. That is a licence fact, not legal advice; read LICENSE.md in the repository for the terms.

## Sources

- [License: Apache-2.0](https://github.com/mock-server/mockserver-monorepo/blob/master/LICENSE)
- [mock-server/mockserver-monorepo on GitHub](https://github.com/mock-server/mockserver-monorepo)
- [Project website](https://www.mock-server.com)
- [README](https://github.com/mock-server/mockserver-monorepo/blob/master/README.md)
- [Releases](https://github.com/mock-server/mockserver-monorepo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mock-server-mockserver-monorepo