mcp-fhir

Name: mcp-fhir
Author: pcmedsinge

ローカル

github.com/pcmedsingeヘルスケア019 週間前に更新

リポジトリ

mcp-fhir について

mcp-fhirは、FHIR R4リソースの読み取り、検索、検証を行うMCPサーバーです。US CoreとIPSプロファイルに対応し、EpicやCernerなどのEHRサンドボックス向けSMART-on-FHIRバックエンド認証も利用できます。

主な機能

01個別のFHIRリソースの読み取り
02FHIRクエリパラメーターによる検索
03ページ分割検索の継続
04US CoreおよびIPSプロファイルによる検証
05SMART-on-FHIR OAuth 2.0認証

活用シーン

01FHIR R4サーバーからの記録取得
02ページ分割による臨床リソース検索
03US CoreまたはIPSプロファイルに沿ったリソース検証
04EpicまたはCernerのEHRサンドボックスへの接続

MCP 対応

stdioまたはSSEで、FHIR機能の確認、読み取り、検索、ページ送り、プロファイル検証を行う5つのツールをMCP対応クライアントに公開します。SMART-on-FHIR認証により、対応するEHRサンドボックスへのリクエストを認証できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "pcmedsinge-mcp-fhir": {
      "command": "uvx",
      "args": [
        "mcp-fhir"
      ],
      "env": {
        "FHIR_BASE_URL": "<FHIR_BASE_URL>",
        "SMART_ENABLED": "<SMART_ENABLED>"
      }
    }
  }
}

起動コマンドuvx mcp-fhir

設定が必要な環境変数

FHIR_BASE_URLBase URL of the FHIR R4 server (default: https://hapi.fhir.org/baseR4)

SMART_ENABLEDSet to 'true' to enable SMART-on-FHIR OAuth 2.0 (Epic/Cerner)

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypimcp-fhir1.1.1stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

mcp-fhir

FHIR R4 MCP サーバー — リソースの読み取り、検索、ページネーション、US Core／IPS プロファイルに対するリソースの検証を行い、 SMART-on-FHIR OAuth 2.0 を介して Epic／Cerner EHR サンドボックスに認証します。
fhir-mcp-suite モノレポの一部です。

概要

mcp-fhir は5 つの MCP ツールを提供し、MCP 互換のあらゆる AI（Claude、GPT-4o など）が、あらゆる FHIR R4 サーバーと対話できるようにします。US Core および IPS プロファイルに対するリソースの検証も、1 つのサーバープロセスで行えます。現在、検索と検証の両方を組み合わせた他の公開 FHIR MCP サーバーはありません。

ツール	説明
`fhir_capabilities`	CapabilityStatement の概要 — サーバーがサポートする機能
`fhir_read`	リソースタイプと論理 ID を指定して、単一のリソースを読み取ります
`fhir_search`	FHIR クエリパラメーターを使ってリソースタイプを検索します。ページネーションがある場合は、`_next_url` を含む Bundle を返します
`fhir_search_next`	`_next_url` のページネーションリンクをたどります（SSRF 対策済み）
`validate_against_profile`	HAPI validator を介してリソースを検証します。US Core と IPS のエイリアスをサポートします

アーキテクチャ

Claude Desktop / AI client
        │  MCP (stdio or SSE)
        ▼
┌───────────────────────────────┐
│        mcp-fhir  v1.1         │
│  ┌───────────────────────────┐│
│  │  tools/                   ││
│  │  ├─ fhir_capabilities.py  ││
│  │  ├─ fhir_read.py          ││
│  │  ├─ fhir_search.py        ││   ──► FHIR R4 server
│  │  └─ validate_profile.py   ││   ──► HAPI validator sidecar
│  └───────────────────────────┘│
│  fhir-mcp-shared               │
│  ├─ LangFuse traces (session)  │
│  ├─ Pydantic structured output │
│  └─ structlog JSON logging     │
└───────────────────────────────┘

クイックスタート

# requires Python 3.12+ and uv
uvx mcp-fhir           # stdio transport (Claude Desktop, default)

# SSE transport (HTTP, for API access)
MCP_TRANSPORT=sse uvx mcp-fhir

Claude Desktop の設定（`claude_desktop_config.json`）

{
  "mcpServers": {
    "mcp-fhir": {
      "command": "uvx",
      "args": ["mcp-fhir"],
      "env": {
        "FHIR_BASE_URL": "https://hapi.fhir.org/baseR4",
        "HAPI_VALIDATOR_URL": "http://localhost:8082"
      }
    }
  }
}

HAPI validator のセットアップ、トラブルシューティング、セルフホスト FHIR サーバーの設定については、インストールガイド全文をご覧ください。

評価結果

ゴールデンクエリスイート — 公開 HAPI デモサーバー（hapi.fhir.org/baseR4）で実行：

カテゴリー	ケース数	合格率
`fhir_capabilities`	2	100 %
`fhir_read`	4	100 %
`fhir_search`	6	100 %
`fhir_search_next`	2	100 %
`validate_against_profile`	6	100 %
合計	20	100 %

CI ゲート：uv run python evals/mcp-fhir/run_eval.py --ci --threshold 0.9
検証ケースには HAPI サイドカーが必要です（docker compose up hapi-validator）。

設定

すべての設定は環境変数で行います（.env.example を参照）：

変数	デフォルト値	説明
`FHIR_BASE_URL`	`https://hapi.fhir.org/baseR4`	FHIR サーバーのベース URL
`HAPI_VALIDATOR_URL`	`http://localhost:8082`	HAPI validator サイドカー（内部ではポート 3500 で実行。`8082:3500` をマッピング）
`FHIR_TIMEOUT_S`	`30`	HTTP タイムアウト（秒）
`FHIR_MAX_RESULTS`	`20`	検索時のデフォルト `_count`
`MCP_TRANSPORT`	`stdio`	`stdio` または `sse`
`MCP_PORT`	`8000`	SSE トランスポートのポート
`LOG_FORMAT`	`json`	`json`（本番環境）または `console`（開発環境）
`LANGFUSE_PUBLIC_KEY`	(未設定)	LangFuse オブザーバビリティ（任意）
`LANGFUSE_SECRET_KEY`	(未設定)	LangFuse オブザーバビリティ（任意）

SMART-on-FHIR 認証

mcp-fhir v1.1.0 では SMART-on-FHIR バックエンドサービス（client_credentials グラント、RFC 6749）が追加され、ブラウザーのリダイレクトなしで、実際の Epic／Cerner サンドボックスにサーバーが認証できるようになりました。

SMART_ENABLED=true の場合、すべての FHIR リクエストに Authorization: Bearer <token> ヘッダーが付与されます。トークンはプロセス内にキャッシュされ、有効期限の 30 秒前に自動更新されます。

SMART 環境変数

変数	デフォルト	説明
`SMART_ENABLED`	`false`	SMART 認証を有効にするには `true` に設定します
`SMART_CLIENT_ID`	`""`	EHR 登録ポータルで取得したアプリのクライアント ID
`SMART_CLIENT_SECRET`	`""`	クライアントシークレット（`SecretStr` として保存され、ログに記録されません）
`SMART_TOKEN_URL`	`""`	トークンエンドポイントの URL。空欄の場合は自動検出されます
`SMART_SCOPES`	`system/*.read`	スペース区切りの OAuth 2.0 スコープ
`SMART_GRANT_TYPE`	`client_credentials`	OAuth のグラントタイプ（`client_credentials` のみサポート）
`SMART_TOKEN_TIMEOUT_S`	`15.0`	トークンリクエストの HTTP タイムアウト

SMART_TOKEN_URL が空欄の場合、サーバーは SMART の自動検出を実行します。
GET {FHIR_BASE_URL}/.well-known/smart-configuration → token_endpoint。
検出結果が 200 以外の場合は、{FHIR_BASE_URL}/oauth2/token にフォールバックします。

Epic サンドボックスのクイックスタート

https://fhir.epic.com/ に登録し、My Apps → バックエンドサービスアプリを作成します。
Client ID と Client Secret を控えます。
モノレポのルートに .env を作成します（すでに .gitignore に追加されています）。

FHIR_BASE_URL=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
SMART_ENABLED=true
SMART_CLIENT_ID=your-epic-client-id
SMART_CLIENT_SECRET=your-epic-client-secret
# SMART_TOKEN_URL is optional — auto-discovered from FHIR_BASE_URL

Cerner サンドボックスのクイックスタート

https://code.cerner.com/ に登録し、バックエンドサービスアプリを作成します。
Client ID とトークンエンドポイントの URL を控えます。
.env を更新します。

FHIR_BASE_URL=https://fhir-ehr-code.cerner.com/r4/your-tenant-id
SMART_ENABLED=true
SMART_CLIENT_ID=your-cerner-client-id
SMART_CLIENT_SECRET=your-cerner-client-secret
SMART_TOKEN_URL=https://authorization.cerner.com/tenants/your-tenant-id/protocols/oauth2/profiles/smart-v1/token

SMART 認証を使用する Claude Desktop の設定

{
  "mcpServers": {
    "mcp-fhir": {
      "command": "uvx",
      "args": ["mcp-fhir"],
      "env": {
        "FHIR_BASE_URL": "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
        "SMART_ENABLED": "true",
        "SMART_CLIENT_ID": "your-epic-client-id",
        "SMART_CLIENT_SECRET": "your-epic-client-secret"
      }
    }
  }
}

プログラムによるクライアント（LangGraph／任意の Python エージェント）

StdioServerParameters を使用して、任意の Python MCP クライアントを FHIR サーバーに接続します。同じパターンは、LangGraph のツールノード、LangChain エージェント、または通常の asyncio スクリプトでも使用できます。

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio, os

server = StdioServerParameters(
    command="uv",
    args=["run", "--package", "mcp-fhir", "mcp-fhir"],
    env={
        **os.environ,
        # ── Public HAPI (no auth) ──────────────────────────────────
        "FHIR_BASE_URL": "https://hapi.fhir.org/baseR4",
        "SMART_ENABLED": "false",

        # ── Epic sandbox (uncomment + fill in) ────────────────────
        # "FHIR_BASE_URL":       "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
        # "SMART_ENABLED":       "true",
        # "SMART_CLIENT_ID":     os.environ["EPIC_CLIENT_ID"],
        # "SMART_CLIENT_SECRET": os.environ["EPIC_CLIENT_SECRET"],

        # ── Cerner sandbox (uncomment + fill in) ──────────────────
        # "FHIR_BASE_URL":       "https://fhir-myrecord.cerner.com/r4/<tenant-id>",
        # "SMART_ENABLED":       "true",
        # "SMART_CLIENT_ID":     os.environ["CERNER_CLIENT_ID"],
        # "SMART_CLIENT_SECRET": os.environ["CERNER_CLIENT_SECRET"],
        # "SMART_TOKEN_URL":     "https://authorization.cerner.com/tenants/<tenant-id>/...",
    },
)

async def main():
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "fhir_search",
                arguments={"resource_type": "Patient", "params": {"_count": "3"}},
            )
            print(result.content[0].text)

asyncio.run(main())

サポート対象のすべてのサーバー（パブリック HAPI、SMART Health IT、Epic、Cerner、ローカル Docker）ですぐに実行できる設定については、demo/fhir_server_configs.py を参照してください。

SMART 統合テストの実行

# Requires real sandbox credentials in .env
uv run pytest packages/mcp-fhir/tests -m smart_integration -v

プロファイル検証

validate_against_profile ツールは、次の省略エイリアスをサポートしています。

エイリアス	プロファイル URL
`us-core-patient`	`http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient`
`us-core-observation`	`http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-clinical-result`
`us-core-condition`	`http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns`
`us-core-medication-request`	`http://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest`
`us-core-encounter`	`http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter`
`ips-patient`	`http://hl7.org/fhir/uv/ips/StructureDefinition/Patient-uv-ips`

プロファイル検証には、HAPI バリデーターのサイドカー（リポジトリのルートにある docker-compose.yml に含まれています）が必要です。

開発

# From monorepo root
uv sync
uv run pytest packages/mcp-fhir/tests -v
# Integration tests (requires HAPI public server access)
uv run pytest packages/mcp-fhir/tests -m integration

アーキテクチャ

Client (Claude / GPT-4o)
    │  MCP protocol (stdio or SSE)
    ▼
mcp-fhir server (Python, anyio)
    ├── fhir_read ──────────► FHIR R4 server (configurable)
    ├── fhir_search ─────────► FHIR R4 server
    └── validate_against_profile
              │
              ▼
        HAPI validator sidecar (markiantorno/validator-wrapper)
              │
              ▼
        LangFuse (optional observability)

ライセンス

Apache-2.0

Markdown 対応

ログインしてコメント

基本情報

作者: pcmedsinge
言語: python
バージョン: 1.1.1
トランスポート: stdio
掲載日: 2026年6月20日
最終更新: 19 週間前
公式 Registry: io.github.pcmedsinge/mcp-fhir

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

mcp-fhir

mcp-fhir について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

mcp-fhir

概要

アーキテクチャ

クイックスタート

Claude Desktop の設定（claude_desktop_config.json）

評価結果

設定

SMART-on-FHIR 認証

SMART 環境変数

Epic サンドボックスのクイックスタート

Cerner サンドボックスのクイックスタート

SMART 認証を使用する Claude Desktop の設定

プログラムによるクライアント（LangGraph／任意の Python エージェント）

SMART 統合テストの実行

プロファイル検証

開発

アーキテクチャ

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

Claude Desktop の設定（`claude_desktop_config.json`）