HL7 v2.5.1 Reference
MCP Server

Available Tools

Eight tools covering the full HL7 v2.5.1 reference surface.

Deep validation profiles

Beyond the base MSH, delimiter, timestamp and code-table checks that run on every message, these five types are validated against their specific semantics:

Quick Start

1. Download the server

   Right-click and save, or clone the repo.

   shell

   curl -O https://coffeemilktea.github.io/mcp/server.js

2. Install dependencies

   shell

   npm install @modelcontextprotocol/sdk express cors zod

3. Run the server

   shell

   node server.js
   # HL7 v2.5.1 MCP server listening on http://localhost:3000/mcp

4. Add to Claude Desktop

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

   claude_desktop_config.json

   {
     "mcpServers": {
       "hl7-reference": {
         "type": "http",
         "url": "http://localhost:3000/mcp"
       }
     }
   }

   Restart Claude Desktop. The eight tools will appear in the tool panel.

5. Or use with Claude Code

   Add to your project's .claude/settings.json:

   .claude/settings.json

   {
     "mcpServers": {
       "hl7-reference": {
         "type": "http",
         "url": "http://localhost:3000/mcp"
       }
     }
   }

Deploy Remotely

Run on Railway or Render for a persistent endpoint you can share across machines.

Railway (one command)

railway init # answer prompts
railway up    # deploys; gives you https://yourapp.up.railway.app

Set PORT env var if needed. Railway auto-detects Node.js.

Render

Create a new Web Service, point to the repo, set Start Command to node server.js. The deployed URL becomes your MCP endpoint — use https://yourapp.onrender.com/mcp.

Environment variables

Supported HL7 Content

Segments

Message Types

Code Tables

Version Traps This Server Encodes

Most HL7 reference material circulating online is a blend of v2.3 through v2.9. These are the points where v2.5.1 specifically differs from what people expect, and where the reference data here has been pinned to the 2.5.1 standard.

Example Prompts

Once connected, you can ask Claude questions like:

# Field lookup
"What does PID-3 contain and what's its data type?"
→ get_field(segment="PID", field=3)

# Message structure
"What segments are required in an ADT A40 merge message?"
→ get_message_structure(messageType="ADT^A40")

# Parse a real message
"Parse this HL7 message and tell me the patient's MRN and accession number."
→ parse_message(message="MSH|^~\&|RIS|HOSP|PACS|HOSP|...")

# Code table lookup
"What does ORC-1 code 'SC' mean?"
→ lookup_code_table(tableNumber="0119", filter="SC")

# Validate before sending
"Validate this ORM^O01 and tell me what's missing."
→ validate_message(message="MSH|^~\&|...")

# Merge integrity
"Is this A40 safe to send? Check the merge direction."
→ validate_message(...)  → catches self-merge, unpaired
                              PID/MRG, cross-authority merge

# Report status consistency
"This ORU says Final but the EMR shows it as preliminary. Why?"
→ validate_message(...)  → cross-checks OBR-25 vs OBX-11

# Segment overview
"Explain the ZDS segment and what it's used for in IHE."
→ get_segment(segment="ZDS")