hl7gen

Generate, validate, and convert synthetic HL7 v2 test data — for any HL7 v2 system, with no vendor lock-in.

pip install hl7gen
hl7gen generate ADT_A01

That's it — no database, no server, no license required. Point the output at whatever you're testing (Mirth, Rhapsody, an IRIS production, your own listener) with hl7gen send.

Why

Testing an HL7 v2 interface means generating realistic-looking messages, and there's surprisingly little good open tooling for that outside of expensive commercial engines. hl7gen fills that gap: a small, free, scriptable tool that generates structurally valid HL7 v2.5 messages for any of ~185 message types, validates messages you already have, and can convert common message types straight to FHIR.

Demo

$ hl7gen generate ADT_A01 --out demo-out
Wrote demo-out/ADT_A01_1.hl7

$ head -c 180 demo-out/ADT_A01_1.hl7
MSH|^~\&|0FH4X5RF^WV4ACSOK^HCD|RW3B2KC7^CI4YOCBC^HCD|3IAHLZ8G^WJUAL9DT^Random|0VOI1TEB^CQO9N5A8^ISO|20070421035225^L|EHDY4XWH|ADT^A01^ADT_A01|IK2IMSPU|P^I|2.5|488.38|B9COA8ZR|NE|AL

$ hl7gen validate demo-out/ADT_A01_1.hl7
Valid HL7 message.

$ hl7gen to-fhir demo-out/ADT_A01_1.hl7
{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "name": [{ "family": "QLMPEPPZ", "given": ["ZTJ5ROEJ", "BN81RG9V"] }]
      }
    }
  ]
}

$ hl7gen types | head -3
ACK          Acknowledgement
ADR_A19      Patient query
ADT_A01      Admit/Visit Notification

Features

• Generate — synthetic HL7 v2.5 messages for any standard message type (ADT_A01, ORU_R01, ORM_O01, ...), fully populated (not just the required-field skeleton).
• Validate — parse and check any HL7 v2 message, yours or generated.
• Convert to FHIR — turn common ADT/ORU/ORM messages into a FHIR Bundle (Patient/Encounter/Observation). See Supported message types below — this is intentionally not universal coverage.
• Send — deliver a message to any TCP/IP HL7 receiver.
• --realistic — optionally use Claude to generate a clinically coherent synthetic patient persona (name, DOB, address, phone) that seeds the message, instead of pure random values. Requires ANTHROPIC_API_KEY; without it, generation just uses Faker-based randomization — the tool is fully usable for free either way.
• Web playground — try it in the browser with no install (docker compose up, see below).
• GitHub Action — generate test HL7 data directly in CI (see action/action.yml).
• MCP server — expose generate/validate/convert as tools any MCP client (Claude Desktop, Claude Code, etc.) can call directly. See MCP server below.

App Layout

<img width="524" alt="image" src="https://github.com/user-attachments/assets/d706bdeb-ba30-46f8-9751-8ee5f074616c" />

CLI

hl7gen generate ADT_A01 --count 5 --out ./messages   # write 5 messages to disk
hl7gen generate ORU_R01 --realistic                  # AI-realistic patient data
hl7gen validate ./messages/ADT_A01_1.hl7
hl7gen to-fhir ./messages/ADT_A01_1.hl7
hl7gen send ./messages/ADT_A01_1.hl7 --host localhost --port 2575
hl7gen types                                          # list all message types
hl7gen structure ADT_A01                              # JSON structure tree

Web playground

Run locally:

docker compose up --build

Open http://localhost:8000 — generate, validate, and convert messages entirely in the browser. Set ANTHROPIC_API_KEY in your environment before docker compose up to enable the realistic-data option there too.

Deploy your own copy to Render: connect this repo on Render via New + → Blueprint — it picks up render.yaml and deploys webapp/Dockerfile automatically (free tier). See decisions/0011-render-for-public-playground.md.

MCP server

pip install "hl7gen[mcp]"

Exposes 5 tools over the Model Context Protocol: generate_hl7_message, validate_hl7_message, hl7_to_fhir, get_hl7_structure, list_hl7_message_types. It runs locally over stdio — an MCP client launches hl7gen-mcp as a subprocess, no network or Docker involved.

For Claude Code: this repo ships a .mcp.json, so opening it in Claude Code makes the server available automatically. For other clients, point them at the hl7gen-mcp command (installed by the mcp extra above). See decisions/0013-mcp-server.md for what's exposed, what's deliberately not (message sending — a side-effecting operation), and why.

Also published as an MCPB bundle for one-click install in compatible hosts — download hl7gen.mcpb from the latest release. It uses the uv runtime type, so dependencies install automatically at first run — no separate pip install needed. See decisions/0014-mcpb-bundle-for-smithery.md.

Claude Code plugin

/plugin marketplace add mwaseem75/hl7gen
/plugin install hl7gen@hl7gen-marketplace

Bundles the MCP server above with a skill (SKILL.md) that teaches Claude when to reach for hl7gen and flags real gotchas discovered while building it (like HL7's \r segment separator getting silently mangled by naive text handling). See decisions/0015-skill-and-plugin.md.

FHIR conversion coverage

hl7gen to-fhir currently supports: ADT_A01, ADT_A02, ADT_A03, ADT_A04, ADT_A05, ADT_A06, ADT_A08, ORU_R01, ORM_O01, SIU_S12. Unsupported types raise a clear error rather than producing a partial or silently wrong conversion — see decisions/0003-fhir-coverage-scope.md.

GitHub Action

- uses: mwaseem75/hl7gen-action@v1
  with:
    message-type: ADT_A01
    count: 10
    out-dir: test-data/hl7

Lives in its own repo: mwaseem75/hl7gen-action — see there for full docs (inputs/outputs, example workflow).

Project layout

src/hl7gen/     core package (generator, validator, fhir_export, ai_realistic, mllp_client, cli)
webapp/         FastAPI web playground + static frontend
action/         GitHub Action wrapping the CLI
tests/          pytest suite
decisions/      one file per architectural decision (ADR-style) — read before changing scope
tasks.md        phase tracker

Development

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.