NyxTools

Posted on Apr 3

How to Parse HL7 Messages with AI — Free MCP Server

#opensource #ai #mcp #healthcare

TL;DR

Install the DICOM/HL7/FHIR MCP Server (pip install dicom-hl7-mcp), add it to Claude Desktop, and paste any HL7 v2.x message. Claude parses every segment, names every field, looks up table values, and explains what the message means in context. Free. No license required. The server covers 15 HL7 segment types, 200+ DICOM tags, and 20+ HL7 code tables.

The Problem

If you've worked in healthcare IT, you've done this a thousand times: someone sends you a raw HL7 message and asks "what's wrong with this?"

MSH|^~\&|RIS|RAD|EMR|HOSP|20240315140000||ORU^R01|MSG003|P|2.5.1
PID|1||MRN12345^^^HOSP^MR||DOE^JOHN||19650315|M
OBR|1|ORD001|ACC001|CTABD^CT Abdomen^L|||20240315130000
OBX|1|FT|&GDT^Report||FINDINGS: Normal CT abdomen.||||||F

You squint at pipe-delimited fields, count positions, check which table F refers to in OBX-11, and try to remember if OBR-18 is the accession number or the placer order number.

According to the HL7 International v2.5.1 specification, there are over 180 segment types and hundreds of code tables. Memorizing them isn't realistic. But an AI tool that knows the spec can look them up instantly.

Setup: 60 Seconds

Step 1: Install the MCP Server

pip install dicom-hl7-mcp

The package is 120KB, pure Python, no compiled dependencies. Works on Python 3.10+.

Step 2: Add to Claude Desktop

Open your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this:

{
  "mcpServers": {
    "dicom-hl7-assistant": {
      "command": "uvx",
      "args": ["dicom-hl7-mcp"]
    }
  }
}

Restart Claude Desktop. Done.

Step 3: Paste and Ask

Paste your HL7 message into Claude and say:

"Parse this HL7 message"

Claude calls the parse_hl7_message tool and returns every field with its name, value, data type, table lookups, and contextual notes.

What You Get

For the message above, Claude returns a full parse with field-level detail:

Segment	Field	Name	Value	Notes
MSH-9	Message Type	ORU^R01	Observation Result/Unsolicited	Radiology report delivery
PID-3	Patient ID List	MRN12345	Medical Record Number	Assigning authority: HOSP
PID-5	Patient Name	DOE^JOHN	Last^First format	PN data type per HL7 spec
OBR-4	Universal Service ID	CTABD^CT Abdomen^L	Procedure code	Local coding system (L)
OBX-11	Result Status	F	Final result	HL7 Table 0085

Plus vendor quirks, cross-references, and integration notes based on 19 years of building PACS, RIS, and HIS interfaces in production healthcare environments.

What the Server Knows

The DICOM/HL7/FHIR MCP Server (built by NyxTools) includes a curated knowledge base drawn from published standards and real-world integration experience:

Coverage	Count	Source
DICOM tags	~200 most common	DICOM PS3.6 (2024b)
HL7 segments	15 (MSH, PID, PV1, OBR, OBX, ORC, and more)	HL7 v2.5.1
HL7 code tables	20+ (Administrative Sex, Patient Class, Result Status, etc.)	HL7 International
FHIR R4 mappings	96 cross-standard mappings	HL7 v2-to-FHIR IG
Vendor private tags	7 vendors (GE, Siemens, Philips, Fuji, Agfa, Canon, Hologic)	Field experience
Integration patterns	7 (ADT feed, order-to-result, IHE SWF, and more)	IHE Technical Framework

5 Free Tools

Tool	What It Does
`lookup_dicom_tag`	Look up any DICOM tag by number or keyword
`explain_dicom_tag`	Detailed explanation with vendor quirks
`parse_hl7_message`	Parse HL7 v2.x messages with field-level detail
`explain_hl7_segment`	Explain any segment's fields and data types
`lookup_hl7_table`	Look up HL7 table values

Free, forever. No license, no sign-up, no email gate.

Premium: Cross-Standard Mapping + PACS Connectivity

The premium tier (v0.2.0, released April 2026) adds 12 more tools:

Cross-standard mapping: DICOM-to-HL7, HL7-to-FHIR with data type conversion notes
Mirth Connect generation: Complete channel XML configs from a use case description
PACS connectivity: C-FIND, C-MOVE, DICOMweb (QIDO-RS, WADO-RS) to query real PACS systems
Study summary: Query a study from PACS and auto-map it through DICOM, HL7, and FHIR in one call

17 tools total. The only MCP server that bridges all three healthcare standards with live PACS connectivity.

Premium license at nyxtools.gumroad.com

FAQ

What HL7 versions does this support?
v2.3 through v2.9, with focus on v2.5.1 (the most widely deployed version in US healthcare). The parser handles any pipe-delimited HL7 v2.x message regardless of version.

Does it work with Mirth Connect?
Yes. The free tier parses messages you're debugging in Mirth. The premium tier generates complete Mirth Connect channel configurations from a use case description.

Can I connect it to my PACS?
With the premium tier and [pacs] extras (pip install dicom-hl7-mcp[pacs]), you can connect via C-FIND/C-MOVE or DICOMweb. Tested with Orthanc, RamSoft, and DCM4CHEE.

Is patient data (PHI) safe?
The free reference tools process standards metadata, not patient data. The PACS connectivity tools include PHI safety: log redaction, result warnings, and optional output redaction. See the PHI Safety section in the README.

What MCP clients work with this?
Any MCP-compatible client. Tested with Claude Desktop, Claude Code, and Cursor.

DEV Community