HealthChain README

Open infrastructure for healthcare data applications.

Connect Python pipelines and applications to live FHIR APIs, build and validate structured output, and deliver it through REST, CDS Hooks, CDA, MCP, or LangChain.

Installation

Terminal

pip install healthchain

What HealthChain Does

HealthChain puts a consistent FHIR boundary around your Python code: live data in, your own logic in the middle, and validated FHIR out. Built for research software, healthcare data, and AI teams.

🔌 Connect to Live FHIR APIs Connect to Epic, Cerner, Medplum, and other FHIR R4 servers through one interface that handles authentication, source routing, and common FHIR operations. Getting Started →	🔥 Build and Validate FHIR Build typed resources without hand-writing deeply nested FHIR. Structured validation identifies failing fields and invalid required codes before delivery. Getting Started →
🤖 Use the Same Tools with Agents Expose the same build, validate, read, and terminology operations over MCP or LangChain, with structured errors an agent can inspect and correct. Getting Started →	💬 Build FHIR-Backed Applications Use live or local FHIR data in research software, patient-facing applications, analytics, decision support, and AI-assisted workflows. Getting Started →

Why HealthChain?

Every healthcare data team rebuilds the same integration layer. Whether your logic is rule-based, a logistic regression, or an agent, it needs authenticated access to real FHIR APIs and a reliable way to turn output into coded FHIR. Pipelines tied to one site's warehouse don't travel, and structural or coding errors may only be discovered downstream.

HealthChain handles that layer so you can focus on your logic and your domain.

Live data, not exports — Connect to live FHIR APIs instead of site-specific warehouse queries and stale extracts
Keep connection details out of pipeline logic — Load endpoints and credentials from environment-backed configuration
Build FHIR with less boilerplate — Use flat, typed helpers instead of manually assembling deeply nested resources
Catch errors early — Get structured validation reports with failing field paths and actionable diagnostics
Resolve codes instead of guessing them — Map free text through a swappable terminology lookup before building a resource
Choose how to deliver the result — Expose output through FHIR REST services, CDS Hooks, SOAP/CDA, MCP, or LangChain

🏆 Recognition & Community

Featured & Presented:

Featured in TLDR AI Newsletter (900K+ developers)
Featured by Medplum for open source integration with Epic
Presented at NHS Python Open Source Conference (watch talk)
Built from NHS AI deployment experience – read the origin story

🤝 Pilots & Partnerships

Exploring HealthChain for your product or organization? Get in touch to discuss integrations, pilots, or collaborations, or join our Discord to connect with the community.

Usage Examples

Build a FHIR Service

Expose Multiple FHIR Sources [Docs]

server.ts

from healthchain.gateway import HealthChainAPI, FHIRGateway
from healthchain.gateway.clients import FHIRAuthConfig
from healthchain.fhir.r4b import Bundle, Patient

# Create a FHIR-connected service
app = HealthChainAPI(title="Multi-EHR Patient Data")

# Credentials are loaded from EPIC_* and CERNER_* environment variables
fhir = FHIRGateway()
fhir.add_source("epic", FHIRAuthConfig.from_env("EPIC").to_connection_string())
fhir.add_source("cerner", FHIRAuthConfig.from_env("CERNER").to_connection_string())

@fhir.aggregate(Patient)
def patient_data(id: str, source: str) -> Bundle:
    """Fetch patient data from any configured FHIR source."""
    bundle = fhir.search(
        Patient,
        {"_id": id},
        source,
        add_provenance=True,
        provenance_tag="healthchain-source",
    )
    return bundle

app.register_gateway(fhir)

# Available at: GET /fhir/aggregate/Patient?id=123&sources=epic&sources=cerner

if __name__ == "__main__":
    app.run(port=8888)

Scaffold with the CLI

Turn a working pipeline into a configurable FHIR service:

bash

healthchain new my-app -t fhir-gateway
cd my-app
healthchain serve

HealthChain CLI scaffolding and running a FHIR Gateway service

Add your logic in app.py. Use healthchain.yaml to configure FHIR sources and service settings while keeping credentials in environment variables. See the CLI reference for all commands.

Agent and Assistant Workflows

Give an Agent FHIR Tools [Docs]

server.ts

from healthchain.tools import FHIRToolkit

# One toolkit: build, validate, read, and code FHIR — as typed agent tools
kit = FHIRToolkit(bundle="patient_bundle.json")

kit.as_mcp().run()          # serve to Claude or any MCP client
tools = kit.as_langchain()  # or drop into a LangChain agent

Or serve the tools straight from the terminal:

bash

healthchain mcp --bundle patient_bundle.json

Build with an AI Assistant

Install the HealthChain plugin to give Claude Code or Codex the current API, CLI, and recipes:

text

# Claude Code
/plugin marketplace add healthchainai/HealthChain
/plugin install healthchain@healthchain

# Codex
codex plugin marketplace add healthchainai/HealthChain
codex plugin add healthchain@healthchain

Or point any assistant at llms.txt for a map of the current API docs.

🛣️ What we're building towards

🔌 Deeper FHIR connectivity — more authentication patterns, write workflows, and real-world examples from pilot deployments
🧪 Broader validation — cover more resource types and value-set bindings, with clearer correction reports and optional server-backed profile validation
🧭 Terminology integrations — connect the TerminologyLookup interface to FHIR terminology servers and licensed vocabularies
🔎 Traceable data movement — carry provenance, validation results, and source errors through transformations and downstream delivery
🧱 Reusable data workflows — strengthen the patterns for moving research extracts, claims, and application data behind consistent FHIR interfaces

🤝 Contributing

Building research software or working with healthcare data? Contribute a cookbook — bring your use case, and I'll personally support you through it
Read CONTRIBUTING.md for guidelines
Technical questions and ideas → GitHub Discussions
Pilots and partnerships → email

🤗 Acknowledgements

This project builds on fhir.resources and CDS Hooks standards developed by HL7 and Boston Children's Hospital.