Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HL7 v2.5.1 Reference MCP Server validate this ORU^R01 message — flag any OBR-25 vs OBX-11 mismatches"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that gives LLMs structured access to the complete HL7 v2.5.1 standard: every segment, field, data type, message structure, trigger event and code table. It also has tools to parse, validate, diff and de-identify messages, and to build ACKs.
It's built for PACS administrators, healthcare IT engineers and interface analysts.
Transports | stdio (default) and Streamable HTTP |
Standard | HL7 v2.5.1, plus the IHE RAD ZDS segment |
Runtime | Node.js 20+ |
License | MIT (data sources are listed in NOTICE) |
Companion server: hl7-v2-fhir-mcp-server answers what does this field become in FHIR R4 and converts whole messages into a transaction Bundle. This server answers what does this segment mean. Both servers share the
hl7v2-coredata package.
v1 | v2 | |
Segments | 15 + ZDS | 149 + ZDS |
Fields | 211 | 2,078. The original 210 hand-written notes are kept. |
Data types | 0 | 89, with components |
Message structures | 16 hand-written | 200, with groups and choices |
Trigger events | 16 | 349 |
Code tables | 13 (240 codes) | 498 (5,955 codes), each code tagged with its v2.5.1 status |
Every table code has a v2.5.1 status:
valid: confirmed in v2.5.1.
not-in-2.5.1: added later or removed earlier; the history says which.
unverified: listed in HL7 Terminology, but no source confirms it for v2.5.1.
lookup_code_table returns only valid codes unless you ask for the others. The validator reports
codes from later versions as errors and unverifiable codes as warnings. See core/NOTICE
for where each piece of data comes from.
Related MCP server: carechronicle-mcp
claude mcp add hl7-reference -- npx -y hl7-v2-mcp-serverOr add it to the project's .mcp.json:
{
"mcpServers": {
"hl7-reference": { "command": "npx", "args": ["-y", "hl7-v2-mcp-server"] }
}
}{
"mcpServers": {
"hl7-reference": { "command": "npx", "args": ["-y", "hl7-v2-mcp-server"] }
}
}The Claude Desktop config is at ~/Library/Application Support/Claude/claude_desktop_config.json
(Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
npx hl7-v2-mcp-server --http # http://localhost:3000/mcp
# or from a clone: npm install && npm start
claude mcp add --transport http hl7-reference http://localhost:3000/mcpVariable | Default | Description |
|
| HTTP port ( |
|
| Bind address ( |
| (unset) | Clients send |
| (loopback) | Extra |
| (none) | Browser origins allowed through CORS. No CORS headers are sent by default. |
|
| Idle sessions are closed after this many milliseconds (default 30 minutes). |
|
| Cap on concurrent sessions. |
|
| Request body limit. |
|
| Larger tool results return an error that explains how to narrow the request. |
/health returns the server name and version. node server.js still starts the HTTP server, as it
did in v1.
All tools are read-only, return structuredContent that matches a published output schema, and
accept lenient input: "3" or 3, table 4 or 0004, and adt_a04, ADT^A04 or ADT A04.
Tool | What it does |
| Lists every segment with its field count. Paginated, with a filter. |
| Full segment definition: each field's data type, optionality (R/O/C/B/W), repetition, length, table and curated notes. |
| One field, with its data type's components and a summary of its table. |
| New. A data type's components and the fields that use it. |
| Every message type^event and the structure it uses. Paginated, with a filter. |
| Abstract message syntax for an event ( |
| Table values with their v2.5.1 status. Defaults to valid codes only. Paginated. |
| New. Searches segments, fields, data types, events, structures, tables and codes by concept ("accession", "discharge date"). |
| Parses to JSON with fields labelled by name and escapes decoded. It also returns a summary (MRN, prior MRN, order control, accession and which field it came from, Study Instance UID, result status). Filter by segment type and page with offset/limit. |
| Base and structural checks, plus deep profiles (below). |
| New. Builds a v2.5.1 ACK: swapped MSH, |
| New. Compares two messages by segment, field, component or subcomponent, using decoded values and field names. MSH-7 and MSH-10 are ignored by default. |
| New. Removes or pseudonymises HIPAA Safe Harbor identifiers by v2.5.1 field and data type (details below). It never returns the original values. |
Resources: hl7v2://segment/{code}, hl7v2://datatype/{code}, hl7v2://table/{id},
hl7v2://structure/{id}, hl7v2://about/sources.
These base checks run on every message:
MSH delimiters.
MSH-7 and other timestamps.
MSH-9 message code, trigger and structure, checked against tables 0076, 0003 and 0354, including whether the structure matches the event.
MSH-10 length.
MSH-11 (table 0103), MSH-12 and MSH-15/16 (table 0155).
Segments that aren't defined in v2.5.1.
EVN-1 agreeing with MSH-9.2.
MSA on ACK messages (MSA-5 is withdrawn in v2.5.1).
Profile | What it checks beyond the base checks |
| EVN; PID; PV1, which is required; an outpatient class on an admission; and that PV1-3, PV1-19 and PV1-44 are present. It also flags a discharge time on an admission. |
| PV1-45 discharge date/time present, PV1-19, and PV1-36 against table 0112 when HL7 publishes values for it. |
| An inpatient class on a registration; PV1-19; and a discharge time on a registration. |
| EVN placement, PV1 required by ADT_A01, PV1-19 missing, and MRG rejected. |
| PV1 required by ADT_A05, PV1-19 populated on a person-level event, and a patient class other than N. |
| PID↔MRG pairing across the repeating PATIENT group, MRG order, self-merge, cross-authority merges, and MRG-2/4 as backward-compatible only. |
| ORC-1 (table 0119), order numbers, action codes on existing orders, SC without ORC-5, ORC↔OBR pairing, OBR-4, the accession, and the ZDS DICOM UID. |
| ORDER groups (ORC, one OBR, at least one IPC). IPC-1 to IPC-4 are required (accession, requested procedure, Study Instance UID, scheduled procedure step). Also checks UID format, DICOM modality coding and consistent accessions. |
| OBX grouped under its OBR, OBR-25 (table 0123) with an explicit callout when a table 0085 code is used, OBX-11 (table 0085), OBX-2 (table 0125: CWE is not a v2.5.1 value type), OBR-25 checked against every OBX-11, NM values that aren't numeric, and repeated OBX-3 without OBX-4. |
| SCH first and present only once; SCH-1 or SCH-2; SCH-6, SCH-16 and SCH-20 required; SCH-11 is backward-compatible only (use TQ1); timing present; RGS groups with AIS, AIG, AIL and AIP inside them; AIS-3; action codes (table 0206). |
deidentify_message follows the HIPAA Safe Harbor list (45 CFR 164.514(b)(2)):
Names: names (XPN) become REDACTED.
Addresses (XAD): only state, country and address type are kept. ZIP codes are dropped.
Contact and personal numbers: phone numbers (XTN), SSNs and licence numbers are removed.
Identifiers: MRNs, account, visit, order, accession and appointment numbers get keyed HMAC pseudonyms. A value always maps to the same pseudonym within a message, and across messages when you pass a seed. Assigning authority and identifier type are kept.
DICOM UIDs (IPC-3, ZDS-1) become new 2.25. UIDs.
Dates: every date, found through the v2.5.1 data types, is cut to the year. dateMode: "shift" shifts dates instead, which isn't Safe Harbor.
Ages over 89: the birth date is dropped.
Free text (OBX-5 TX/FT/ST, NTE-3, PV2-12) and embedded ED/RP data are redacted.
Local Z-segments are dropped by default.
You still need to review the output: Safe Harbor also requires that you have no actual knowledge that what remains could identify the person.
Most HL7 material online blends v2.3 to v2.9. These are the places where v2.5.1 differs from what people expect.
Trap | The v2.5.1 position |
CE vs CWE | In v2.5.1 the coded fields are |
CWE in OBX-2 | Table 0125 in v2.5.1 has no CWE, CNE or DTM value types. They were added in v2.6 and v2.7. |
Table 0123 vs 0085 | OBR-25 uses table 0123 (O, I, S, A, P, C, R, F, X, Y, Z). OBX-11 uses table 0085 (C, D, F, I, N, O, P, R, S, U, W, X). Putting an OBX-11 code in OBR-25 is the most common ORU build error. M and N appear in table 0123 only in later versions. |
PID-39 | v1 of this README said PID ends at PID-38. That was wrong: v2.5.1 defines PID-39 Tribal Citizenship (CWE). |
PD1-8 | Organ Donor Code is PD1-8. PD1-6 is Handicap. |
MSA-5 | Withdrawn (W) in v2.5.1. Don't populate it. |
MRG-2 / MRG-4, SCH-11 | Backward compatibility only (B). Carry prior identifiers as MRG-1 repeats, and timing in TQ1. |
ZDS | IHE RAD TF-2 defines exactly one field, of type |
ORC and PID in ORU | Both are optional in the ORU_R01 abstract syntax, so the validator warns rather than errors. |
Repeating groups | ADT_A39 repeats |
SCH-9 vs SCH-11 | Appointment Duration is SCH-9, with its units in SCH-10. SCH-11 is the backward-compatible TQ timing field. |
Table 0078 | The off-scale abnormal flags are |
OBR-18 accession | Using OBR-18 for the DICOM Accession Number is an IHE RAD convention. |
MSH-3 / MSH-5 | Optional in the standard, so they're reported as warnings. |
"What does PID-3 contain and what's its data type?" → get_field
"Where does the accession number go in an OMI?" → search_definitions, get_message_structure
"Is OBR-25 = M valid in 2.5.1?" → lookup_code_table(0123, status: all)
"Validate this SIU^S12 and build the ACK I should send back." → validate_message, generate_ack(fromValidation)
"What changed between these two A08s?" → diff_messages
"Strip the PHI from this ORU so I can paste it in a ticket." → deidentify_messagenpm install # installs the core workspace too
npm test # unit, MCP integration (in-memory), HTTP security and stdio tests
npm run fetch-sources && npm run generate # rebuild core/data from the upstream sourcesThe layout:
core/: the hl7v2-core package (data, parser, search).
src/server.js: the tool and resource registry.
src/tools/: the tools.
src/validate/: validation profiles.
src/transport/: stdio and HTTP.
bin/cli.js: the entry point.
Don't expose the server without authentication. If you bind a non-loopback HOST without an
API_KEY, the server refuses to start.
HOST=0.0.0.0 API_KEY="$(openssl rand -hex 32)" ALLOWED_HOSTS=hl7.example.org npx hl7-v2-mcp-server --httpThe server accepts whatever message you POST. Treat remote instances as lab or synthetic-data playgrounds, never as a place to send real PHI.
hl7-v2-fhir-mcp-server: the companion v2-to-FHIR mapping and conversion server
coffeemilktea.github.io: browser-based healthcare IT tools
hl7-dicom-tools: DICOM and HL7 v2 browser tools
HL7® and FHIR® are registered trademarks of Health Level Seven International. This project isn't affiliated with or endorsed by HL7 International. MIT licensed; see LICENSE and NOTICE.
This server cannot be deployed
HL7 FHIR R4 health-data API for AI agents: free sandbox, 30 synthetic patients, AI-ready context.
Telehealth support for Claude, Codex and Cursor: investigate cases and connect your tools.
HealthGuard - 12-tool health/medical AI safety MCP: PII redaction, HIPAA, GDPR Art.9.
Privacy-preserving synthetic health data generation. FHIR R4/R5 compliant.
