MLLP Server

Getting Started

Run your first MLLP server in under 5 minutes.

Prerequisites

  • Pre-built binaries have no runtime dependencies.
  • netcat (nc) — used in the test step below to send a raw MLLP frame.

Download a pre-built binary

Pre-built binaries are available for Linux, macOS, and Windows on both amd64 and arm64 architectures. Download the archive for your platform from the Downloads page.

PlatformArchive
Linux amd64mllp-server_<version>_linux_amd64.tar.gz
Linux arm64mllp-server_<version>_linux_arm64.tar.gz
macOS amd64mllp-server_<version>_darwin_amd64.tar.gz
macOS arm64mllp-server_<version>_darwin_arm64.tar.gz
Windows amd64mllp-server_<version>_windows_amd64.zip
Windows arm64mllp-server_<version>_windows_arm64.zip

Extract and run:

tar -xzf mllp-server_<version>_linux_amd64.tar.gz
./mllp-server

A checksums.txt file is included in every release so you can verify the download:

sha256sum --check checksums.txt

Start the server

Run the binary with no arguments. The server listens on :2575 by default, which is the standard IANA-assigned port for MLLP:

./mllp-server

Override the listen address or adjust logging with environment variables:

LISTEN_ADDR=:3000 LOG_LEVEL=debug ./mllp-server

Key environment variables at startup:

VariableDefaultDescription
LISTEN_ADDR:2575TCP address and port to listen on
LOG_LEVELinfoLog verbosity: trace, debug, info, warn, error
IDLE_TIMEOUT30sClose connections idle longer than this
MAX_CONNECTIONS0Max concurrent connections; 0 means unlimited

See the Configuration reference for the full list.

Send a test message

With the server running, send a minimal ADT A01 HL7 message wrapped in an MLLP frame. The frame uses a vertical tab (0x0B) as the start block, and file separator + carriage return (0x1C 0x0D) as the end block:

printf '\x0bMSH|^~\\&|SENDING_APP|SENDING_FAC|RECV_APP|RECV_FAC|20240101120000||ADT^A01|MSG001|P|2.3\r\x1c\x0d' | nc localhost 2575

A successful delivery prints the ACK response from the server. If you see no output or a connection refused error, check that the server started cleanly and that LISTEN_ADDR matches the port you are connecting to.

Add a connector

Connectors route incoming HL7 messages to downstream systems. Create a config.yaml file with an HTTP connector that forwards every message to a local endpoint:

connectors:
  - name: log-sink
    type: http
    url: http://localhost:8080/hl7
    filter: "true"

The filter field is a CEL expression. The value 'true' matches all messages. You can narrow delivery to specific message types, for example 'msh.msg_type == "ADT"'.

Start the server with the connector config:

CONNECTORS_CONFIG=config.yaml ./mllp-server

Send the test message again and your HTTP endpoint will receive the HL7 payload in the request body.

Next steps