halaxy-mcp

Ein MCP Server für die Halaxy Praxisverwaltungs-API, geschrieben in Python. Er ermöglicht es einem MCP-Client (Claude, GitHub Copilot, etc.), Fragen zu beantworten wie „Was steht heute in meinem Kalender?“, „Welche heutigen Termine wurden noch nicht abgerechnet?“ oder „Welche Rechnungen sind bei einem bestimmten Versicherer offen?“, indem er mit Ihrem eigenen Halaxy-Konto spricht.

Dies ist ein kleines, mandantenfähiges Tool, das für den eigenen Gebrauch einer Praxis gebaut wurde, kein allgemeiner Halaxy-SDK – siehe Was es bewusst nicht tut unten.

Werkzeuge

• list_invoices(date) – Rechnungen mit einem bestimmten Datum (Standard: heute). Jede Rechnung hat ein payer_name (immer vorhanden) und ein patient-Objekt (nur vorhanden, wenn der Zahlungspflichtige ein tatsächlicher Patient ist, nicht ein Versicherer/Arbeitgeber).

• list_appointments(date, appointment_type) – Termine für einen bestimmten Tag, jeweils gekennzeichnet als "session" (ein echter Kliententermin) oder "meeting" (ein Blocker/Erinnerung/interne Notiz – alles ohne verknüpften Patienten). Sitzungen enthalten außerdem:

  • session_mode – "F2F" oder "Telehealth", aufgelöst aus dem HealthcareService, gegen den der Termin gebucht ist

  • patient – id/name/initials/telecom/patient_status/is_active_client (siehe Patientendaten unten)

  • invoice – die verknüpfte Rechnung, falls eine erstellt wurde, über Halaxys direkte Termin→Rechnung-Referenz (zuverlässiger als Abgleich nach Datum – siehe die Hinweise im Code)

  • awaiting_insurer_invoice – nur befüllt, wenn noch keine Rechnung existiert und der Patient eine aktive Coverage auf Datei hat, die als „an eine Organisation abgerechnet“ markiert ist – d. h. kennzeichnet eine Sitzung, die voraussichtlich an einen Versicherer/Arbeitgeber abgerechnet wird, aber noch nicht abgerechnet wurde

  • referrals – die aktiven Überweisung(en) des Patienten (siehe list_referrals unten), sodass die aktuelle Sitzungsanzahl direkt dort steht, ohne einen zweiten Aufruf

• list_practitioners() – klinisches Personal, jeweils mit PractitionerRole-ID und Name, sodass ein Client „Was steht heute für Alice an?“ in eine Rollen-ID auflösen kann, bevor er sie mit list_appointments abgleicht.

• list_invoices_by_payer(payer_name) – jede Rechnung, die jemals an einen bestimmten Versicherer/Arbeitgeber/Organisation (z. B. „Acme Insurance“) gestellt wurde, nicht an ein Datum gebunden – durchsucht Halaxys Invoice?recipient= direkt, hat also nicht den Blindspot des Rückblickfensters von list_invoices (siehe unten).

• list_referrals(flag) – jede aktive Überweisung in der Praxis – Halaxys Modell für eine Hausarzt-/andere Überweisung, die eine bestimmte Anzahl von Sitzungen und/oder Dollar unter einem Finanzierungsschema autorisiert (am häufigsten ein Medicare Mental Health Treatment Plan – „6 Sitzungen zum Start“, wie die meisten es kennen – aber auch DVA, WorkCover usw.). Jede enthält sessions_total/sessions_used/sessions_remaining, amount_total/amount_used, Ablaufdatum und berechnete flags: "over_limit" (verwendet ≥ autorisiert), "expiring_soon" (endet innerhalb von 30 Tagen), "expired". Optional kann nach nur einem Flag gefiltert werden – z. B. „wem gehen die Sitzungen bald aus“.

Erforderliche Halaxy-API-Schlüssel-Bereiche

Erstellen Sie einen API-Schlüssel in Halaxy (Einstellungen → API-Schlüssel) mit denjenigen, die Sie benötigen – der Server degradiert elegant, wenn ein Bereich deaktiviert ist, er schlägt nur bei den Tools fehl, die ihn benötigen:

Beispiel dafür, wie das in Halaxys eigenem API-Schlüssel-Bereichsbildschirm aussieht:

Patientendaten

Dieser Server minimiert bewusst, was er über einen Patienten preisgibt. Halaxys Patient-Ressource enthält auch Geburtsdatum, Adresse, Geschlecht, Notfallkontakt und Überweisungsquellen-Notizen – nichts davon wird hier benötigt, und das wird im Code erzwungen (ALLOWED_PATIENT_FIELDS in halaxy_mcp.py), nicht nur durch Konvention: Jede Patientensuche wird auf id/name/initials/telecom/patient_status/is_active_client gefiltert, bevor sie den MCP-Client erreichen kann, unabhängig davon, was angefragt wird.

Klinische/Sitzungsnotizen sind über diese API überhaupt nicht abrufbar, für keinen Schlüssel oder Bereich. Halaxys eigene /metadata-Fähigkeitserklärung zeigt, dass seine klinische Notizen-Ressource (DocumentReference) nur create/patch unterstützt – kein Lesen, was dem entspricht, was die Halaxy-UI selbst zeigt (Klinische Notizen haben nur einen Erstellen-Schalter). Dies ist eine Einschränkung der gesamten API, nicht etwas, das dieser Server bewusst nicht offenlegt.

Überweisungen und Sitzungslimits

Halaxy modelliert einen Hausarzt-Mental-Health-Behandlungsplan (und ähnliche – DVA, WorkCover) als Referral, das mit einer ReferralDefinition verknüpft ist (der Überweisungstyp, der das Sitzungs-/Dollar-Limit trägt – z. B. wurde eine echte ReferralDefinition in Tests wörtlich „Medicare: MHTP Referral“ genannt mit einem 6-Sitzungs-Limit). sessions_remaining wird nicht direkt von Halaxy zurückgegeben; es wird hier als sessions_total - sessions_used berechnet.

Ein paar Dinge, die anhand echter Daten bestätigt wurden und die Sie wissen sollten, wenn Sie dies weiter ausbauen:

• Ein Patient kann mehr als eine gleichzeitig aktive Überweisung haben (z. B. eine pro überwiesenem Praktiker) – dieser Server versucht nicht, „die“ zu erraten; er gibt alle zurück.

• sessions_used kann in der Praxis sessions_total überschreiten (Medicare stoppt Buchungen nicht hart an der Obergrenze) – dafür ist das "over_limit"-Flag da.

• Einige Überweisungsdatensätze haben überhaupt keine strukturierte Art/Überweiser, nur einen Freitext-comment – wird so angezeigt, wenn das der einzige Hinweis ist.

• Halaxys eigenes active-Feld an einer Überweisung scheint nicht automatisch auf false zu wechseln, sobald der Zeitraum abläuft – die "expired"/"expiring_soon"-Flags werden aus period.end berechnet, nicht von active abgelesen.

Wenn ein Bereich nicht aktiviert ist

Jedes Tool benötigt den passenden Bereich, der für den verwendeten API-Schlüssel aktiviert ist (siehe Tabelle oben). Wenn ein Bereich fehlt, antwortet Halaxy mit einem 401/403 oder einem OperationOutcome-Fehler – der Server wirft einen klaren HalaxyPermissionError (mit Benennung der Ressource, des HTTP-Status und des eigenen Fehlertexts von Halaxy), anstatt dies stillschweigend als „null Ergebnisse“ zu behandeln. Ohne diese Prüfung würden ein fehlender Bereich und ein wirklich leeres Ergebnis (z. B. „heute keine Rechnungen“) für den MCP-Client identisch aussehen.

Installation

Erfordert Python 3.10+.

git clone https://github.com/ryanhunt/halaxy-mcp.git
cd halaxy-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# then edit .env with your Halaxy API key's client_id/client_secret

Kurzer Check, dass es läuft:

source .venv/bin/activate
python3 halaxy_mcp.py

Es wird nichts ausgeben und einfach dasitzen – das ist korrekt, es wartet darauf, dass ein MCP-Client über stdin/stdout mit ihm spricht. Ctrl+C zum Beenden.

Einbindung in einen MCP-Client

Alle diese starten dasselbe Skript als lokalen Unterprozess und kommunizieren über stdio mit ihm – kein Netzwerkport, keine separate Bereitstellung. Verwenden Sie in jedem Fall den vollständigen, absoluten Pfad zum Python des .venv und zu halaxy_mcp.py.

Claude Desktop – fügen Sie zu claude_desktop_config.json hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "halaxy-mcp": {
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

Beenden Sie die App danach vollständig und öffnen Sie sie erneut (nicht nur das Fenster schließen).

VS Code (GitHub Copilot) – fügen Sie .vscode/mcp.json in einem Arbeitsbereich hinzu:

{
  "servers": {
    "halaxy-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

GitHub Copilot CLI – fügen Sie zu ~/.copilot/mcp-config.json hinzu (oder führen Sie /mcp add in der CLI aus):

{
  "mcpServers": {
    "halaxy-mcp": {
      "type": "local",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"],
      "tools": ["*"]
    }
  }
}

In keinem dieser Fälle ist ein env-Block erforderlich – das Skript lädt seine eigene .env-Datei aus dem Verzeichnis neben halaxy_mcp.py.

Bekannte Einschränkungen, die man kennen sollte

• Das Rückblickfenster von list_invoices kann Rechnungen übersehen. Halaxys Invoice-Suche hat keinen Parameter für das eigene date-Feld der Rechnung, nur created/_lastUpdated – daher holt list_invoices Rechnungen, die in den letzten 45 Tagen erstellt wurden, und filtert clientseitig nach exakter date-Übereinstimmung. Rechnungen an Versicherer/Arbeitgeber (z. B. Arbeiterunfall) werden manchmal Monate vor der Sitzung erstellt, für die sie schließlich datiert sind, was außerhalb dieses Fensters liegen kann. list_appointments hat dieses Problem nicht (es folgt direkt der Termin→Rechnung-Verknüpfung), und list_invoices_by_payer auch nicht (es sucht nach Empfänger, ohne Datumsgrenze) – bevorzugen Sie diese, wenn der datumsbasierte Blindspot wichtig ist.

• session vs. meeting wird daraus abgeleitet, ob der Termin einen verknüpften Patient-Teilnehmer hat, nicht aus einem expliziten Halaxy-Feld – eine echte Sitzung, die ohne Verknüpfung eines Patientendatensatzes in Halaxy gebucht wird, würde als Besprechung falsch kategorisiert.

• Es sind absichtlich keine Schreiboperationen (Erstellen/Aktualisieren von irgendetwas) implementiert.

• Nur stdio-Transport – eine Remote/HTTP-Variante (um dies irgendwo zu hosten, das für einen cloudbasierten MCP-Client erreichbar ist, z. B. einen benutzerdefinierten Connector) ist noch nicht gebaut.

Was es bewusst nicht tut

Dies umschließt eine Handvoll schreibgeschützter Endpunkte, die den eigenen Anforderungen einer Praxis entsprechen, keinen allgemeinen Halaxy/FHIR-Client. Es implementiert keine Patientenerstellung/-aktualisierung, klinische Notizen, Terminplanänderungen oder den größten Teil von Halaxys ~50-Ressourcen-FHIR-Oberfläche (Überweisungs-Tracking ist abgedeckt – siehe oben –, aber nicht das Erstellen/Aktualisieren von Überweisungen). Wenn Sie mehr von der API benötigen, sind die Tool-Funktionen in halaxy_mcp.py ein recht kurzer, lesbarer Ausgangspunkt zur Erweiterung.

Lizenz

GPLv3 – siehe LICENSE.