clinical-mcp

Ein MCP-Server für klinische Arbeitsabläufe: synthetische FHIR-R4-Patientenakten durchsuchen und zusammenfassen, Literatur aus PubMed abrufen und Freitext anonymisieren – alles von Claude (oder einem beliebigen MCP-Client) aus.

Als Referenz-MCP-Server gebaut: Er implementiert die gesamte Spezifikationsfläche (Tools, Ressourcen und Prompts – die meisten öffentlichen Server beschränken sich auf Tools), wird mit einer Testsuite geliefert, die das Drahtprotokoll übt, und läuft über stdio oder authentifiziertes streambares HTTP.

Alle Patientendaten sind synthetisch, generiert von Synthea. In diesem Projekt existiert keinerlei echte PHI.

Architecture

[Claude / MCP client]
        |  stdio  or  streamable-http (+ bearer auth)
        v
[clinical-mcp  (MCPServer)]
   |-- tools ------ search_patients, get_patient_summary, get_observations,
   |                search_pubmed, get_pubmed_abstract, deidentify_text
   |-- resources -- fhir://patients            (roster)
   |                fhir://patients/{id}       (full record, URI template)
   |-- prompts ---- clinical_summary, literature_review
   |
   +-- FhirStore ----------- in-memory index over Synthea FHIR R4 bundles
   +-- PubMedClient -------- NCBI E-utilities, rate-limited (3/s, 10/s w/ key)
   +-- deidentify() -------- HIPAA Safe Harbor regex redaction

Quick start

pip install clinical-mcp

Claude Desktop / Claude Code-Konfiguration (mcpServers-Eintrag):

{
  "clinical": {
    "command": "clinical-mcp",
    "env": { "CLINICAL_MCP_DATA_DIR": "/path/to/fhir/bundles" }
  }
}

Aus dem Quellcode:

git clone https://github.com/sarathi-aiml/clinical-mcp
cd clinical-mcp
pip install -e ".[dev]"
clinical-mcp                       # stdio, serves the bundled 10-patient sample
pytest                             # 33 tests, no network needed

Dann fragen Sie Claude zum Beispiel:

"Finden Sie Patientinnen über 50 mit Bluthochdruck, fassen Sie die erste zusammen und rufen Sie die drei aktuellsten PubMed-Artikel ab, die für ihre Medikamentenliste relevant sind."

Tools

Ressourcen stellen dieselben Daten adressierbar bereit (fhir://patients/{id}), sodass Clients einen vollständigen Patientendatensatz als Kontext anhängen können, ohne einen Tool-Roundtrip. Prompts kodieren die beiden Arbeitsabläufe, die ich am häufigsten verwende – Zusammenfassung der Patientenakte und patientenbasierte Literaturrecherche – als wiederverwendbare Vorlagen.

HTTP transport with auth

CLINICAL_MCP_API_KEY=$(openssl rand -hex 32) clinical-mcp --transport http --port 8000

Jede Anfrage muss Authorization: Bearer <key> enthalten; der Server weigert sich, ohne Authentifizierung über HTTP zu starten. stdio (die Standardeinstellung) benötigt keinen Schlüssel – der Transport ist die Vertrauensgrenze.

Data

Das Repository enthält 10 beschnittene synthetische Patienten unter data/sample/. Für einen größeren Korpus:

python scripts/fetch_data.py --out data/full            # ~1,100 patients
CLINICAL_MCP_DATA_DIR=data/full clinical-mcp

--trim reduziert Bundles auf die Ressourcentypen, die der Server tatsächlich liest (Patient, Condition, MedicationRequest, Observation, AllergyIntolerance, Encounter, Immunization, Procedure, DiagnosticReport, CarePlan) und begrenzt Typen mit hohem Volumen.

De-identification: scope and limits

deidentify_text ist ein regex-basiertes Safe-Harbor-Screening: Es erfasst die Identifikatorformate, die in strukturiertem klinischem Text vorkommen, und schwärzt zusätzlich jeden Patientennamen, der im Store geladen ist. Es ist keine zertifizierte De-Identifizierungs-Pipeline – Freitextnamen ohne Anrede, Tippfehler und Identifikatoren in seltenen Kontexten werden durchkommen. Für echte PHI benötigen Sie einen trainierten NER-Durchlauf (z. B. Philter oder einen LLM-Durchlauf mit menschlicher Überprüfung) als zusätzliche Ebene; dieses Tool ist der deterministische erste Filter, und seine Zählungen pro Kategorie machen Audits kostengünstig.

What breaks at 500K documents a week

1. Der In-Memory-Speicher. Alles wird beim Start in den RAM geladen; ~10.000 Patienten sind komfortabel, ~100.000 nicht, und die Startzeit wächst linear. Erste Lösung: SQLite/DuckDB mit Indizes auf Name, Geburtsdatum und Diagnosecodes hinter derselben FhirStore-Schnittstelle. Echte Lösung: Den Speicher auf einen echten FHIR-Endpunkt (HAPI oder eine Cloud-FHIR-API) ausrichten und die Tools zu dünnen Übersetzungsschichten über FHIR-Suchparameter machen.

2. Ein Patient pro Bundle. Der Loader geht von Syntheas Layout aus. Gemischte Bundles benötigen Referenzauflösung (subject.reference) anstelle von Datei-Gruppierung.

3. PubMed-Ratenlimits. 3 Anfragen/s (10 mit Schlüssel) sind interaktiv in Ordnung und in Stapelverarbeitung nutzlos. Bei hohem Volumen benötigen Sie einen lokalen Cache mit Abfrage-Hash und TTL sowie Batch-efetch (bis zu 200 PMIDs pro Anfrage) anstelle von Einzelartikel-Aufrufen.

4. Regex-De-Identifizierungs-Recall. Bei 500.000 Dokumenten pro Woche leckt selbst ein Recall von 99 % Tausende von Identifikatoren. Die Zählausgabe ist genau für diese Messung konzipiert: Stichprobe, Audit und Gate auf gemessenem Recall – dann ein NER-Modell in die Pipeline aufnehmen.

5. Einzelprozess-HTTP. Streambares HTTP unter uvicorn auf einem Prozess bedient ein Team, keine Flotte. Horizontale Skalierung erfordert zustandslose Sitzungen (der Speicher ist schreibgeschützt, daher ist dies größtenteils kostenlos) hinter einem Lastenausgleich und Ratenbegrenzung pro Client am Gateway.

Development

pip install -e ".[dev]"
pytest              # protocol-level + unit tests, PubMed mocked
ruff check .

Docker:

docker build -t clinical-mcp .
docker run --rm -i clinical-mcp                                   # stdio
docker run --rm -p 8000:8000 -e CLINICAL_MCP_API_KEY=secret \
  clinical-mcp --transport http --host 0.0.0.0

License

MIT