halaxy-mcp

Pythonで書かれた、Halaxyの診療管理API用のMCPサーバーです。MCPクライアント（Claude、GitHub Copilotなど）が、自分のHalaxyアカウントと通信して、「今日の予定は？」「今日の予約のうちまだ請求書が発行されていないものは？」「特定の保険者に対して未払いの請求書は？」といった質問に答えられるようにします。

これは、1つの診療所の独自の用途のために作られた小規模なシングルテナントツールであり、汎用のHalaxy SDKではありません。詳細は下記の意図的に行わないことを参照してください。

ツール

• list_invoices(date) - 指定された日付（デフォルトは今日）の請求書を一覧表示します。各請求書にはpayer_name（常に存在）とpatientオブジェクト（支払い者が実際の患者であり、保険者や雇用主でない場合にのみ存在）があります。

• list_appointments(date, appointment_type) - 指定された日の予約を一覧表示します。各予約は"session"（実際のクライアント予約）または"meeting"（ブロッカー/リマインダー/内部メモ - リンクされた患者がいないもの）のいずれかにタグ付けされます。セッションにはさらに以下が含まれます：

  • session_mode - "F2F"または"Telehealth"。予約が行われているHealthcareServiceから解決されます。

  • patient - id/name/initials/telecom/patient_status/is_active_client（下記の患者データを参照）

  • invoice - 請求書が発行されている場合、Halaxyの直接的な予約→請求書参照を介したリンクされた請求書（日付によるマッチングよりも信頼性が高い - コード内の注記を参照）

  • awaiting_insurer_invoice - まだ請求書がなく、かつ患者が「組織に請求」とフラグ付けされた有効なCoverageを保持している場合にのみ設定されます。つまり、保険者/雇用主に請求される予定だがまだ請求されていないセッションを示します。

  • referrals - 患者の有効なReferral（下記のlist_referralsを参照）。これにより、現在のセッション数を追加の呼び出しなしで確認できます。

• list_practitioners() - 臨床スタッフの一覧。各スタッフにはPractitionerRole IDと名前が含まれます。クライアントは「今日のアリスの予定は？」をロールIDに解決してからlist_appointmentsと照合できます。

• list_invoices_by_payer(payer_name) - 特定の保険者/雇用主/組織（例：「Acme Insurance」）に請求されたすべての請求書。日付に縛られません。HalaxyのInvoice?recipient=を直接検索するため、list_invoicesのルックバックウィンドウの盲点（下記参照）がありません。

• list_referrals(flag) - 診療所内のすべての有効なReferral。GPやその他の紹介が資金提供スキーム（最も一般的なのはMedicareメンタルヘルストリートメントプラン - 多くの人が知っている「最初の6セッション」ですが、DVA、WorkCoverなどもあります）の下でセッション数や金額を承認するHalaxyのモデルです。各Referralにはsessions_total/sessions_used/sessions_remaining、amount_total/amount_used、有効期限、および計算されたflags（"over_limit"（使用済み≥承認済み）、"expiring_soon"（30日以内に終了）、"expired"）が含まれます。オプションで1つのフラグに絞り込むこともできます（例：「セッションを使い切りそうな人」）。

必要なHalaxy APIキーのスコープ

HalaxyでAPIキーを作成する際（設定 → APIキー）、必要なスコープを選択してください。スコープが無効な場合、サーバーは正常に動作を続け、そのスコープを必要とするツールでのみ失敗します。

HalaxyのAPIキースコープ画面での表示例：

患者データ

このサーバーは、患者に関する情報を意図的に最小限にしています。HalaxyのPatientリソースには生年月日、住所、性別、緊急連絡先、紹介元のメモも含まれますが、ここではそれらは不要です。これは単なる慣習ではなく、コード（halaxy_mcp.py内のALLOWED_PATIENT_FIELDS）で強制されています。すべての患者検索は、MCPクライアントに到達する前にid/name/initials/telecom/patient_status/is_active_clientに絞り込まれます。

臨床/セッションノートは、どのキーやスコープでもこのAPIからは一切取得できません。 Halaxy自身の/metadata機能ステートメントは、その臨床ノートリソース（DocumentReference）がcreate/patchのみをサポートし、読み取りはサポートしないことを示しています。これはHalaxy UI自体が示す内容（Clinical NotesにはCreateトグルのみ）と一致しています。これはAPI全体の制限であり、このサーバーが意図的に公開しないというわけではありません。

Referralとセッション制限

Halaxyは、GPメンタルヘルストリートメントプラン（および同様のもの - DVA、WorkCover）を、ReferralDefinition（紹介のタイプで、セッション/金額の上限を持ちます。例：テスト中の実際のReferralDefinitionは文字通り「Medicare: MHTP Referral」という名前で、6セッションの制限がありました）にリンクされたReferralとしてモデル化します。sessions_remainingはHalaxyから直接返されず、ここではsessions_total - sessions_usedとして計算されます。

• 患者は同時に複数の有効なReferralを持つことができます（例：紹介先の開業医ごとに1つ）。このサーバーは「その」1つを推測しようとはせず、すべてを返します。

• 実際にはsessions_usedがsessions_totalを超えることがあります（Medicareは上限で予約を強制停止しません）。それが"over_limit"フラグの目的です。

• 一部のReferralレコードには構造化されたタイプや紹介者がまったくなく、自由テキストのcommentのみがあります。それが唯一の手がかりである場合は、そのまま表示されます。

• Halaxy自身のReferralのactiveフィールドは、期間が経過しても自動的にfalseに切り替わらないようです。"expired"/"expiring_soon"フラグはperiod.endから計算され、activeから読み取られるわけではありません。

スコープが有効でない場合

各ツールは、使用しているAPIキーに対応するスコープが有効になっている必要があります（上記の表を参照）。スコープが欠落している場合、Halaxyは401/403またはOperationOutcomeエラーで応答します。サーバーは、それを黙って「結果ゼロ」として扱うのではなく、明確なHalaxyPermissionError（リソース名、HTTPステータス、Halaxy自身のエラーテキストを含む）を発生させます。このチェックがないと、スコープの欠落と本当に空の結果（例：「今日の請求書はありません」）はMCPクライアントにとって同じように見えてしまいます。

インストール

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

動作確認：

source .venv/bin/activate
python3 halaxy_mcp.py

何も出力せず、そのまま待機します。それが正しい動作です。stdin/stdoutを介してMCPクライアントからの通信を待っています。停止するにはCtrl+Cを押してください。

MCPクライアントへの接続

これらはすべて同じスクリプトをローカルサブプロセスとして起動し、stdioを介して通信します。ネットワークポートも個別のデプロイも不要です。すべての場合において、.venvのPythonとhalaxy_mcp.pyへの完全な絶対パスを使用してください。

Claude Desktop - claude_desktop_config.json（macOSでは~/Library/Application Support/Claude/claude_desktop_config.json）に追加：

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

その後、アプリを完全に終了して再度開いてください（ウィンドウを閉じるだけでは不十分です）。

VS Code（GitHub Copilot） - ワークスペースに.vscode/mcp.jsonを追加：

{
  "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 - ~/.copilot/mcp-config.jsonに追加（またはCLI内で/mcp addを実行）：

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

これらのいずれにもenvブロックは不要です。スクリプトはhalaxy_mcp.pyの隣にある独自の.envファイルを読み込みます。

既知の制限事項

• list_invoicesのルックバックウィンドウは請求書を見逃す可能性があります。 HalaxyのInvoice検索には、請求書自体のdateフィールドのパラメータがなく、created/_lastUpdatedのみがあります。そのため、list_invoicesは過去45日間に作成された請求書を取得し、クライアント側で正確なdate一致をフィルタリングします。保険者/雇用主に請求される請求書（例：労災）は、最終的に日付が付けられるセッションの数か月前に作成されることがあり、そのウィンドウの外に落ちる可能性があります。list_appointmentsにはこの問題はありません（予約→請求書のリンクを直接たどります）。list_invoices_by_payerも同様です（受信者で検索し、日付に制限されません）。日付ベースの盲点が問題になる場合は、これらを優先してください。

• sessionとmeetingの区別は、予約にリンクされたPatient参加者がいるかどうかから推測されます。明示的なHalaxyフィールドからではありません。Halaxyで患者レコードをリンクせずに予約された実際のセッションは、会議として誤分類される可能性があります。

• 書き込み操作（作成/更新など）は意図的に実装されていません。

• stdioトランスポートのみです。リモート/HTTPバリアント（クラウドベースのMCPクライアントから到達可能な場所にホストするため、例：カスタムコネクタ）はまだ構築されていません。

意図的に行わないこと

これは、1つの診療所のニーズに合わせた少数の読み取り専用エンドポイントをラップするものであり、汎用のHalaxy/FHIRクライアントではありません。患者の作成/更新、臨床ノート、スケジュール変更、またはHalaxyの約50リソースのFHIRサーフェスのほとんどは実装していません（紹介の追跡はカバーされています - 上記参照 - ただし紹介の作成/更新は含みません）。APIのより多くの部分が必要な場合、halaxy_mcp.py内のツール関数は、拡張するための比較的短く読みやすい出発点です。

ライセンス

GPLv3 - LICENSEを参照してください。