Healthcare FHIR Data MCP Server

Query FHIR R4 healthcare data through Claude or any MCP-compatible client. Look up patients, observations, medications, clinical documents, and parse HL7 v2 messages — all through natural language.

Disclaimer: This is a developer tool for building healthcare integrations. It is NOT a clinical decision-making tool. Do not use with real PHI in production without a BAA with your FHIR server provider.

Quick Start

Claude Desktop

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "healthcare-fhir": {
      "url": "https://your-apify-actor-url/runs/standby"
    }
  }
}

Local Development

git clone <repo>
cd healthcare-fhir
pip install -r requirements.txt
FHIR_BASE_URL=https://your-server.example.org/fhir/r4 python src/server.py

Configuration

Parameter	Description	Required	Default
FHIR_BASE_URL	FHIR R4 server base URL	Yes	—
FHIR_AUTH_HEADER	Authorization header value (e.g., Bearer token)	No	—

Available Tools

get_patient

Look up a patient by FHIR resource ID or Medical Record Number (MRN).

• Parameters: patient_id (str, optional), mrn (str, optional) — at least one required
• Returns: FHIR Patient resource with demographics

list_observations

Query patient observations (vitals, lab results).

• Parameters: patient_id (str, required), category (str, optional — e.g., "vital-signs", "laboratory"), date_from (str, optional), date_to (str, optional)
• Returns: Bundle of Observation resources

list_medications

Get a patient's medication list.

• Parameters: patient_id (str, required), status (str, default "active")
• Returns: Bundle of MedicationRequest resources

get_document_reference

Retrieve clinical document references for a patient.

• Parameters: patient_id (str, required), type_code (str, optional)
• Returns: Bundle of DocumentReference resources

parse_hl7_message

Parse a raw HL7 v2 message into structured JSON.

• Parameters: message (str, required)
• Returns: Structured JSON with parsed segments (MSH, PID, OBR, OBX, etc.)

fhir_search

Generic FHIR search across any resource type.

• Parameters: resource_type (str, required), params (dict, required)
• Returns: FHIR Bundle search results

Disclaimer: This is a developer tool for building healthcare integrations. It is NOT a clinical decision-making tool. Do not use with real PHI in production without a BAA with your FHIR server provider.

Example Prompts

1. "Look up patient with MRN 12345678"
2. "Show me the latest vital signs for patient abc-def"
3. "What medications is patient xyz currently taking?"
4. "Find all lab results for patient 123 from the last 30 days"
5. "Parse this HL7 message: MSH|^~\&|SendingApp|..."

Pricing

Plan	Price	Includes
Monthly	$99/mo	Unlimited tool calls, all 6 tools, FHIR R4 support, HL7 v2 parsing

Local Development

# Install dependencies
pip install -r requirements.txt

# Point to a FHIR test server
export FHIR_BASE_URL=https://your-server.example.org/fhir/r4

# Run the server
python src/server.py

Troubleshooting

• 401 Unauthorized: Verify FHIR_AUTH_HEADER is set correctly (e.g., "Bearer your-token")
• Connection refused: Ensure FHIR_BASE_URL is reachable from the server
• HL7 parse errors: Ensure the message uses standard segment separators (\r or \n) and pipe (|) field delimiters
• Empty results: Check that the patient ID exists on the target FHIR server

Disclaimer: This is a developer tool for building healthcare integrations. It is NOT a clinical decision-making tool. Do not use with real PHI in production without a BAA with your FHIR server provider.