FHIR Spec Navigator (MCP Server)

Ein Model Context Protocol Server, der FHIR R4 StructureDefinitions navigierbar macht. Du kannst damit Ressourcen-Definitionen, Elemente, Kardinalitaeten, Referenzen und Terminologie-Bindings direkt aus deiner KI-Umgebung abfragen.

Der Server liest FHIR-Pakete aus dem lokalen Package-Cache (~/.fhir/packages/) und holt HTML-Dokumentation von hl7.org bei Bedarf nach.

Teil des CEIR-OS Implementation Guide.

Verfuegbare Tools

Tool	Beschreibung
list_resources	Listet FHIR R4 Typen aus dem lokalen Package-Cache (filterbar nach kind)
get_elements	Gibt alle Elemente einer Ressource mit Pfad, Typen und Kardinalitaet zurueck
get_required_elements	Gibt nur die Pflicht-Elemente einer Ressource zurueck (min >= 1)
get_references	Zeigt alle Reference-Elemente und deren erlaubte Ziel-Ressourcen
get_bindings	Gibt Terminologie-Bindings fuer kodierte Elemente zurueck (ValueSet, Strength)
get_element_detail	Detaillierte Informationen zu einem einzelnen Element (Definition, Constraints, etc.)
get_resource_metadata	Metadaten einer Ressource (URL, Status, Beschreibung, Basis-Definition)
get_documentation	Holt die menschenlesbare Dokumentation von hl7.org/fhir/R4
search_documentation	Durchsucht die Dokumentation einer Ressource nach bestimmten Begriffen
compare_resources	Vergleicht die Elemente zweier Ressourcen (gemeinsame, unterschiedliche)

Voraussetzungen

Du brauchst einen lokalen FHIR Package Cache unter ~/.fhir/packages/. Dieser wird automatisch angelegt, wenn du eines der folgenden Tools verwendest:

• SUSHI (beim Kompilieren von FSH-Dateien)
• FHIR Terminal
• Beliebiges FHIR-Tooling, das den FHIR Package Cache nutzt

Mindestens das Paket hl7.fhir.r4.core#4.0.1 sollte vorhanden sein.

Lokal ausfuehren

# Abhaengigkeiten installieren
pip install -e .

# Server starten (stdio-Modus fuer Claude Code/Desktop)
fhir-spec

Fuer den SSE-Modus (HTTP):

MCP_TRANSPORT=sse MCP_HOST=127.0.0.1 MCP_PORT=8080 fhir-spec

Mit Docker ausfuehren

# Image bauen
docker build -t fhir-spec-mcp .

# Container starten (FHIR-Cache vom Host mounten)
docker run -d \
  --name fhir-spec-mcp \
  -p 8080:8080 \
  -v ~/.fhir/packages:/root/.fhir/packages:ro \
  fhir-spec-mcp

Oder mit dem vorgebauten Image:

docker run -d \
  --name fhir-spec-mcp \
  -p 8080:8080 \
  -v ~/.fhir/packages:/root/.fhir/packages:ro \
  ghcr.io/bih-cei/fhir-spec-mcp:latest

Zusaetzliche FHIR-Pakete laden

Ueber die Umgebungsvariable FHIR_PACKAGES kannst du weitere FHIR-Pakete konfigurieren (kommagetrennt):

docker run -d \
  --name fhir-spec-mcp \
  -p 8080:8080 \
  -v ~/.fhir/packages:/root/.fhir/packages:ro \
  -e FHIR_PACKAGES="hl7.fhir.r4.core#4.0.1,de.basisprofil.r4#1.5.0,de.medizininformatikinitiative.kerndatensatz.person#2025.0.0" \
  fhir-spec-mcp

Die angegebenen Pakete muessen im gemounteten FHIR-Cache vorhanden sein.

Umgebungsvariablen

Variable	Standard	Beschreibung
MCP_HOST	127.0.0.1	Bind-Adresse des Servers
MCP_PORT	8080	Port des Servers
MCP_TRANSPORT	stdio	Transport-Modus (stdio oder sse)
FHIR_PACKAGES	(leer)	Kommagetrennte Liste zusaetzlicher FHIR-Pakete
FHIR_SPEC_CACHE	~/.cache/fhir-spec	Verzeichnis fuer gecachte HTML-Dokumentation

Lizenz

MIT