mcp-fhir

Name: mcp-fhir
Author: pcmedsinge

本地服务

github.com/pcmedsinge健康医疗019 周前更新

代码仓库

关于 mcp-fhir

mcp-fhir 是用于读取、搜索和验证 FHIR R4 资源的 MCP 服务，支持 US Core 和 IPS 配置文件。它还支持 SMART-on-FHIR 后端认证，可连接 Epic 和 Cerner 等 EHR 沙盒。

主要功能

01读取单个 FHIR 资源
02使用 FHIR 查询参数搜索
03继续分页搜索
04按 US Core 和 IPS 配置文件验证
05SMART-on-FHIR OAuth 2.0 认证

适用场景

01从 FHIR R4 服务获取记录
02分页搜索临床资源
03按 US Core 或 IPS 配置文件验证资源
04连接 Epic 或 Cerner EHR 沙盒

MCP 相关

它通过 stdio 或 SSE 向兼容 MCP 的客户端提供五种工具，用于查询 FHIR 能力、读取、搜索、分页和配置文件验证。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 提供 五个 MCP 工具，让任何兼容 MCP 的 AI（Claude、GPT-4o 等）都能通过单个服务进程与任意 FHIR R4 服务交互，并验证资源是否符合 US Core 和 IPS 配置文件。目前，还没有其他公开的 FHIR MCP 服务同时提供搜索和验证功能。

工具	描述
`fhir_capabilities`	CapabilityStatement 摘要 — 服务支持的功能
`fhir_read`	按资源类型和逻辑 ID 读取单个资源
`fhir_search`	使用 FHIR 查询参数搜索资源类型；结果为 Bundle，分页时包含 `_next_url`
`fhir_search_next`	跟进 `_next_url` 分页链接（带 SSRF 防护）
`validate_against_profile`	通过 HAPI 验证器验证资源；支持 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 验证器设置、故障排除和可自托管 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 sidecar（docker compose up hapi-validator）。

配置

所有设置均通过环境变量配置（参见 .env.example）：

变量	默认值	描述
`FHIR_BASE_URL`	`https://hapi.fhir.org/baseR4`	FHIR 服务基础 URL
`HAPI_VALIDATOR_URL`	`http://localhost:8082`	HAPI 验证器 sidecar（内部运行于端口 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`	(unset)	LangFuse 可观测性（可选）
`LANGFUSE_SECRET_KEY`	(unset)	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`	设置为 `true` 以启用 SMART 身份验证
`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。
在 monorepo 根目录创建 .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 Agent）

使用 StdioServerParameters，将任意 Python MCP 客户端连接到 FHIR 服务。同样的模式也适用于 LangGraph 工具节点、LangChain Agent 或普通的 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())

参见 demo/fhir_server_configs.py，其中提供了所有受支持服务的可直接运行配置（公共 HAPI、SMART Health IT、Epic、Cerner、本地 Docker）。

运行 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 验证器 sidecar（包含在仓库根目录的 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

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

mcp-fhir

关于 mcp-fhir

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

mcp-fhir

功能

架构

快速开始

Claude Desktop 配置（claude_desktop_config.json）

评测结果

配置

SMART-on-FHIR 身份验证

SMART 环境变量

Epic 沙盒快速入门

Cerner 沙盒快速入门

使用 SMART 身份验证的 Claude Desktop 配置

编程式客户端（LangGraph / 任意 Python Agent）

运行 SMART 集成测试

配置文件验证

开发

架构

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

Claude Desktop 配置（`claude_desktop_config.json`）