FHIR MCP Server

Fast Healthcare Interoperability Resources（FHIR）API 用 Model Context Protocol（MCP）サーバー

目次

• Fast Healthcare Interoperability Resources（FHIR）API 用 Model Context Protocol（MCP）サーバー
  • 目次
  • 概要
  • デモ
    • HAPI FHIR サーバーでのデモ
    • EPIC Sandbox でのデモ
  • 主な機能
  • 前提条件
  • インストール
    • PyPI パッケージを使用したインストール
    • ソースからのインストール
    • Docker を使用したインストール
      • Docker で MCP サーバーを実行する
      • HAPI FHIR サーバーで Docker Compose を使用する
  • MCP クライアントとの統合
    • VS Code
    • Claude Desktop
    • MCP Inspector
  • 設定
    • CLI オプション
    • 環境変数
  • ツール
  • 開発とテスト
    • 開発用依存関係のインストール
    • テストの実行

概要

FHIR MCP サーバーは、FHIR API とシームレスに統合する Model Context Protocol（MCP）サーバーです。開発者、インテグレーター、医療分野のイノベーター向けに設計されており、最新の AI／LLM ツールと医療データをつなぐ橋渡しとして機能します。臨床情報の検索、取得、分析を簡単に行えます。

デモ

HAPI FHIR サーバーでのデモ

この動画では、公開されているHAPI FHIR サーバーに接続した際の MCP サーバーの機能を紹介します。この例では、認証フローを必要としないオープンな FHIR サーバーと直接やり取りする様子を紹介しています。

https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf

EPIC Sandbox でのデモ

この動画では、Epic EHR エコシステムにおける MCP サーバーの機能を紹介します。OAuth 2.0 Authorization Code Grant フローの全体を示しています。

https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de

主な機能

• MCP 互換のトランスポート：stdio、SSE、または streamable HTTP を介して FHIR を提供します

• SMART-on-FHIR ベースの認証サポート：FHIR サーバーおよびクライアントに対して安全に認証します

• FHIRPath によるレスポンスフィルタリング：カスタムの FHIRPath 式を使用して、read および search 操作で返されるリソースやバンドルをフィルタリングし、タスクに必要なフィールドのみを取得することで、ペイロードサイズを削減します。

• ツール統合：VS Code、Claude Desktop、MCP Inspector など、あらゆる MCP クライアントと統合できます

前提条件

• Python 3.8+
• 依存関係管理用のuv
• アクセス可能な FHIR API サーバー

インストール

Python パッケージをインストールするか、このリポジトリをクローンして FHIR MCP Server を使用できます。

PyPI パッケージを使用したインストール

1. 環境変数を設定します：

   サーバーを実行するには、FHIR_SERVER_BASE_URL を設定する必要があります。

   • 認証を有効にする場合： FHIR_SERVER_BASE_URL、FHIR_SERVER_CLIENT_ID、FHIR_SERVER_CLIENT_SECRET、および FHIR_SERVER_SCOPES を設定します。認証はデフォルトで有効になっています。
   • 認証を無効にする場合： FHIR_SERVER_DISABLE_AUTHORIZATION を True に設定します。

   デフォルトでは、MCP サーバーは http://localhost:8000 で実行されます。FHIR_MCP_HOST と FHIR_MCP_PORT を使用してホストとポートをカスタマイズできます。

   以下のように環境変数としてエクスポートするか、.env ファイルを作成して設定できます（.env.example を参照してください）。

   export FHIR_SERVER_BASE_URL=""
   export FHIR_SERVER_CLIENT_ID=""
   export FHIR_SERVER_CLIENT_SECRET=""
   export FHIR_SERVER_SCOPES=""
   
   export FHIR_MCP_HOST="localhost"
   export FHIR_MCP_PORT="8000"
   

2. PyPI パッケージをインストールしてサーバーを実行します

   uvx fhir-mcp-server
   

ソースからのインストール

1. リポジトリをクローンします：

   git clone <repository_url>
   cd <repository_directory>
   

2. 仮想環境を作成し、依存関係をインストールします：

   uv venv
   source .venv/bin/activate
   uv pip sync requirements.txt
   

   または pip を使用します：

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

3. 環境変数を設定します： サンプルファイルをコピーし、必要に応じてカスタマイズします：

   cp .env.example .env
   

4. サーバーを実行します：

   uv run fhir-mcp-server
   

Docker を使用したインストール

Docker で MCP サーバーを実行する

一貫性のある分離された環境で MCP サーバーを実行するには、Docker を使用できます。

認証に関する注意： Docker または Docker Compose を使用して MCP サーバーをローカルで実行する場合は、環境変数 FHIR_SERVER_DISABLE_AUTHORIZATION=True を設定して認証を無効にしてください。この問題は今後のリリースで修正される予定です。

1. Docker イメージをビルドするか、コンテナーレジストリから Docker イメージをプルします：

   • ソースからビルド：

     docker build -t fhir-mcp-server .
     

   • GitHub Container Registry からプル：

     docker pull wso2/fhir-mcp-server:latest
     

2. 環境変数を設定します

   サンプルの環境ファイルをコピーし、必要に応じて編集します：

   cp .env.example .env
   # FHIR サーバーやクライアントの認証情報などを設定するため、.env を編集します。
   

   代わりに、-e フラグを使用して環境変数を直接渡すか、機密情報には Docker secrets を使用できます。利用可能な環境変数の詳細については、設定セクションを参照してください。

3. コンテナーを実行します

   docker run --env-file .env -p 8000:8000 fhir-mcp-server
   

   これによりサーバーが起動し、ポート 8000 で公開されます。必要に応じてポートマッピングを調整してください。

HAPI FHIR Server で Docker Compose を使用する

FHIR MCP サーバーと HAPI FHIR サーバー（PostgreSQL を使用）の両方をすばやくセットアップするには、付属の docker-compose.yml を使用してください。これにより、FHIR 操作のテストにすぐ使える開発環境が構築されます。

1. 前提条件：

   • Docker と Docker Compose がインストールされていること。

2. スタックを起動する：

   docker-compose up -d
   

   このコマンドを実行すると、次の処理が行われます。

   • PostgreSQL データベースのコンテナを起動します。
   • PostgreSQL に接続された HAPI FHIR サーバーを起動し、http://localhost:8080 でリッスンします。
   • FHIR MCP サーバーのコンテナをビルドして実行し、FHIR_SERVER_BASE_URL に http://hapi-r4-postgresql:8080/fhir を設定して、http://localhost:8000 でリッスンします。

3. サービスにアクセスする：

   • FHIR MCP サーバー：http://localhost:8000
   • HAPI FHIR サーバー：http://localhost:8080
   • 停止するには docker-compose down を実行します。

4. 追加の環境変数を設定する：

   OAuth やその他の設定をカスタマイズする必要がある場合は、docker-compose.yml の環境変数を調整してください。Compose ファイルには基本的な設定が含まれています。すべてのオプションについては、設定のセクションを参照してください。

MCP クライアントとの統合

FHIR MCP サーバーは、さまざまな MCP クライアントとシームレスに統合できるように設計されています。

VS Code

VS Code（> V1.104）の MCP 設定ファイルに、次の JSON ブロックを追加してください。Ctrl + Shift + P を押して MCP: Open User Configuration と入力することで追加できます。

"servers": {
    "fhir": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
    }
}

"servers": {
    "fhir": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/fhir-mcp-server",
            "run",
            "fhir-mcp-server",
            "--transport",
            "stdio"
        ],
        "env": {
            "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
        }
    }
}

"servers": {
    "fhir": {
        "type": "sse",
        "url": "http://localhost:8000/sse",
    }
}

Claude Desktop

ローカルの MCP サーバーに接続するには、Claude Desktop の設定に次の JSON ブロックを追加してください。

• Claude Desktop アプリを起動し、上部のメニューバーにある Claude メニューをクリックして、「Settings…」を選択します。
• 設定パネルの左側のサイドバーで「Developer」をクリックし、「Edit Config」をクリックします。ファイルシステム上に設定ファイルが開きます。まだ存在しない場合は、Claude が次の場所に自動的に作成します。
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• 任意のテキストエディターで claude_desktop_config.json ファイルを開きます。MCP サーバーを登録するには、内容を次の JSON ブロックに置き換えてください。

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/mcp"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/sse"
            ]
        }
    }
}

MCP Inspector

MCP Inspector を起動して使用するには、次の手順に従ってください。

• ターミナルを開き、次のコマンドを実行します。

  npx -y @modelcontextprotocol/inspector

• MCP Inspector のインターフェイスで、次のように設定します。

MCP サーバーがすでに起動しており、上記のエンドポイントでリッスンしていることを確認してください。

接続すると、MCP Inspector を使ってツールの呼び出しを可視化し、リクエストとレスポンスのペイロードを確認し、ツールの実装を簡単にデバッグできます。

設定

CLI オプション

次のコマンドラインフラグを使用して、MCP サーバーの動作をカスタマイズできます。

• --transport

  • 説明：MCP サーバーがクライアントとの通信に使用するトランスポートプロトコルを指定します。
  • 使用可能な値：stdio、sse、streamable-http
  • デフォルト：streamable-http

• --log-level

  • 説明：サーバーのログ出力レベルを設定します。
  • 使用可能な値：DEBUG、INFO、WARN、ERROR（大文字と小文字は区別されません）
  • デフォルト：INFO

• --help

  • 説明：使用可能なサーバーオプションを含むヘルプメッセージを表示して終了します。
  • 使用方法：コマンドラインインターフェースによって自動的に提供されます。

使用例：

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
uv run fhir-mcp-server --help

環境変数

MCP サーバーの設定：

• FHIR_MCP_HOST：MCP サーバーがバインドするホスト名または IP アドレスです（ローカルからのアクセスのみにする場合は localhost、すべてのインターフェースで待ち受ける場合は 0.0.0.0 など）。
• FHIR_MCP_PORT：MCP サーバーがクライアントからのリクエストを待ち受けるポートです（例：8000）。
• FHIR_MCP_SERVER_URL：設定されている場合、ホストとポートから URL を生成する代わりに、この値をサーバーのベース URL として使用します。カスタム URL を設定する場合や、プロキシの背後で使用する場合に便利です。
• FHIR_MCP_REQUEST_TIMEOUT：MCP サーバーから FHIR サーバーへのリクエストのタイムアウト時間（秒）です（デフォルト：30）。

FHIR サーバーとの MCP サーバー OAuth2 設定（MCP クライアント ↔ MCP サーバー）： これらの変数は、FHIR サーバーを使用する OAuth2 認可コードグラントフローによる、MCP クライアントから MCP サーバーへの安全な接続を設定します。

• FHIR_SERVER_CLIENT_ID：FHIR サーバーで MCP クライアントを認可するために使用する OAuth2 クライアント ID です。
• FHIR_SERVER_DISABLE_AUTHORIZATION：True に設定すると、MCP サーバーの認可チェックを無効にし、公開アクセス可能な FHIR サーバーへの接続を許可します。
• FHIR_SERVER_CLIENT_SECRET：FHIR クライアント ID に対応するクライアントシークレットです。トークン交換時に使用します。
• FHIR_SERVER_BASE_URL：FHIR サーバーのベース URL です（例：https://hapi.fhir.org/baseR4）。ツール URI の生成と FHIR リクエストのルーティングに使用します。
• FHIR_SERVER_SCOPES：FHIR 認可サーバーに要求する OAuth2 スコープをスペース区切りで指定します（例：user/Patient.read user/Observation.read）。get_user ツールでユーザーコンテキストを取得できるようにするには、fhirUser openid を追加します。この 2 つのスコープが設定されていない場合、ID トークンにユーザーの FHIR リソースへの参照が含まれないため、get_user ツールは空の結果を返します。
• FHIR_SERVER_ACCESS_TOKEN：FHIR サーバーへのリクエストの認証に使用するアクセストークンです。この変数が設定されている場合、サーバーは OAuth2 認可フローを省略し、すべてのリクエストにこのトークンを直接使用します。

メモ

FHIR_SERVER_ACCESS_TOKEN は、対話型 OAuth 認証を省略するための便宜的な手段として、ローカルの stdio モードでデプロイする場合のみを対象としています。MCP サーバーをネットワークまたはパブリックインターネットに公開する場合は、この変数を使用しないでください。

ツール

• get_capabilities：指定された FHIR リソースタイプに関するメタデータを取得します。対応している検索パラメーターやカスタム操作が含まれます。

  • type：FHIR リソースタイプ名（例：「Patient」、「Observation」、「Encounter」）

• search：指定されたリソースタイプに対して標準の FHIR 検索インタラクションを実行し、一致するリソースのバンドルまたはリストを返します。

  • type：FHIR リソースタイプ名（例：「MedicationRequest」、「Condition」、「Procedure」）。
  • searchParam：FHIR 検索パラメーター名と設定する値の対応付け（例：{"family":"Simpson","birthdate":"1956-05-12"}）。
  • response_filter_fhirpaths：（任意）レスポンスバンドル内のリソースに適用する FHIRPath 式の配列（例：["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]）。

• read：FHIR の「read」インタラクションを実行し、リソースタイプとリソース ID を指定して単一のリソースインスタンスを取得します。検索パラメーターまたはカスタム操作を指定して、レスポンスをさらに絞り込むこともできます。

  • type：FHIR リソースタイプ名（例：「DiagnosticReport」、「AllergyIntolerance」、「Immunization」）。
  • id：特定の FHIR リソースインスタンスの論理 ID。
  • searchParam：FHIR 検索パラメーター名と設定する値の対応付け（例：{"device-name":"glucometer"}）。
  • operation：リソースに定義されたカスタム FHIR 操作または拡張クエリの名前（例：「$everything」）。
  • response_filter_fhirpaths：（任意）返される単一のリソース（または $everything などのカスタム操作を使う場合はエントリー）をフィルタリングする FHIRPath 式の配列（例：["Patient.name", "Observation.valueQuantity"]）。

• create：指定したタイプの新しいリソースを保存するため、FHIR の「create」インタラクションを実行します。

  • type：FHIR リソースタイプ名（例：「Device」、「CarePlan」、「Goal」）。
  • payload：作成する FHIR リソースの全内容を表す JSON オブジェクト。
  • searchParam：FHIR 検索パラメーター名と設定する値の対応付け（例：{"address-city":"Boston"}）。
  • operation：リソースに定義されたカスタム FHIR 操作または拡張クエリの名前（例：「$evaluate」）。

• update：指定されたペイロードで既存のリソースインスタンスの内容を置き換え、FHIR の「update」インタラクションを実行します。

  • type：FHIR リソースタイプ名（例：「Location」、「Organization」、「Coverage」）。
  • id：特定の FHIR リソースインスタンスの論理 ID。
  • payload：FHIR リソースの完全な JSON 表現。必須要素と任意のデータが含まれます。
  • searchParam：FHIR 検索パラメーター名と設定する値の対応付け（例：{"patient":"Patient/54321","relationship":"father"}）。
  • operation：リソースに定義されたカスタム FHIR 操作または拡張クエリの名前（例：「$lastn」）。

• delete：特定のリソースインスタンスに対して、FHIR の「delete」インタラクションを実行します。

  • type：FHIR リソースタイプ名（例：「ServiceRequest」、「Appointment」、「HealthcareService」）。
  • id：特定の FHIR リソースインスタンスの論理 ID。
  • searchParam：FHIR 検索パラメーター名と設定する値の対応付け（例：{"category":"laboratory","issued:"2025-05-01"}）。
  • operation：リソースに定義されたカスタム FHIR 操作または拡張クエリの名前（例：「$expand」）。

• get_user：現在認証されているユーザーの FHIR リソース（リンクされた Patient リソースなど）を取得し、id、name、birthDate など、利用可能な人口統計情報を含む簡潔なプロフィールを返します。

開発とテスト

開発用依存関係のインストール

テストを実行し、開発に参加するには、テスト用の依存関係をインストールします。

pip を使用する場合：

# Install project in development mode with test dependencies
pip install -e '.[test]'

# Or install from requirements file
pip install -r requirements-dev.txt

uv を使用する場合：

# Install development dependencies
uv sync --dev

テストの実行

このプロジェクトには、主要な機能をすべて網羅する包括的なテストスイートが含まれています。

# Simple test runner
python run_tests.py

# Or direct pytest usage
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server

pytest を使用する場合：

pytest tests/

これにより、tests/ ディレクトリ内のすべてのテストが検出され、実行されます。

テストの特長：

• 100 件以上のテストで包括的にカバー
• pytest-asyncio を使用した完全な async/await サポート
• HTTP リクエストと外部依存関係の完全なモック化
• ターミナル出力と HTML 出力によるカバレッジレポート
• 実際のネットワーク呼び出しがない高速な実行

テストスイートには、以下が含まれています。

• ユニットテスト：コア機能のテスト
• 統合テスト：コンポーネント間の連携を検証
• エッジケースのカバレッジ：エラー処理と検証のシナリオ
• モック化された OAuth フロー：現実的な認証テスト

詳細な分析のため、カバレッジレポートは htmlcov/index.html に生成されます。