Mcp Fhir

io.github.pcmedsinge由 GitHub 账号 pcmedsinge 发布v1.1.1更新于 Oct 24, 2026

FHIR R4 read/search/validate MCP server — US Core/IPS profiles, SMART-on-FHIR auth (Epic/Cerner).

已验证STDIO仅桌面安全与监控数据与分析

概览

AI 生成的概览

让助手读取、搜索、分页并对照 US Core/IPS 配置验证 FHIR R4 医疗资源，可选向 Epic 或 Cerner 沙箱认证。

可以做什么
通过 stdio 提供五个工具：fhir_capabilities 汇总 FHIR 服务器的 CapabilityStatement，fhir_read 按资源类型和逻辑 ID 读取单个资源，fhir_search 使用 FHIR 查询参数并返回带 _next_url 的 Bundle，fhir_search_next 在 SSRF 防护下跟进分页链接，validate_against_profile 通过 HAPI 验证器边车对照 US Core 或 IPS 配置校验资源。还可使用 SMART-on-FHIR 后端服务向 Epic 或 Cerner EHR 沙箱认证。
适用场景
适合助手需要浏览或查询 FHIR R4 临床数据服务器、获取患者或观察资源，或对照 US Core 与 IPS 配置校验资源的场景。适用于针对公共演示服务器或 EHR 沙箱的医疗数据原型与集成工作。
运行要求
作为本地 Python 包运行（需 Python 3.12+ 与 uv，通过 uvx 启动）。需要 FHIR_BASE_URL 指向 FHIR R4 服务器，默认使用公共 HAPI 演示服务器。配置验证需要 HAPI 验证器边车，由 HAPI_VALIDATOR_URL 配置。SMART 认证需要 SMART_ENABLED 以及 SMART_CLIENT_ID 和 SMART_CLIENT_SECRET，SMART_TOKEN_URL 可选。可选的 LangFuse 密钥用于可观测性。
安装前请注意
当 SMART_ENABLED=true 时，请求会携带 bearer 令牌，服务器需要 SMART_CLIENT_ID 和 SMART_CLIENT_SECRET，这些是真实的 EHR 凭据，应避免纳入版本控制。查询会发往 FHIR_BASE_URL 指定的服务器，临床数据可能离开本机；默认是公共演示服务器。可选的 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY 会把可观测性追踪发送给第三方。工具为只读，但数据属于敏感健康信息。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Fhir，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

mcp-fhir

FHIR R4 MCP server — read, search, paginate, validate resources against US Core/IPS profiles, and authenticate against Epic/Cerner EHR sandboxes via SMART-on-FHIR OAuth 2.0.
Part of the fhir-mcp-suite monorepo.

[PyPI] [PyPI - Python Version] [CI] [License]

What it does

mcp-fhir exposes five MCP tools that let any MCP-compatible AI (Claude, GPT-4o, etc.) interact with any FHIR R4 server — and validate resources against US Core and IPS profiles — in a single server process. No other public FHIR MCP server combines search + validation today.

ToolDescription
fhir_capabilitiesCapabilityStatement summary — what the server supports
fhir_readRead a single resource by type + logical ID
fhir_searchSearch a resource type with FHIR query params; returns Bundle with _next_url when paginated
fhir_search_nextFollow a _next_url pagination link (SSRF-guarded)
validate_against_profileValidate a resource via the HAPI validator; supports US Core & IPS aliases

Architecture

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     │└───────────────────────────────┘

Quick start

bash
# requires Python 3.12+ and uvuvx mcp-fhir           # stdio transport (Claude Desktop, default)
# SSE transport (HTTP, for API access)MCP_TRANSPORT=sse uvx mcp-fhir

Claude Desktop config (claude_desktop_config.json)

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

See full installation guide for HAPI validator setup, troubleshooting, and self-hosted FHIR server configuration.

Eval results

Golden query suite — run against the public HAPI demo server (hapi.fhir.org/baseR4):

CategoryCasesPass rate
fhir_capabilities2100 %
fhir_read4100 %
fhir_search6100 %
fhir_search_next2100 %
validate_against_profile6100 %
Total20100 %

CI gate: uv run python evals/mcp-fhir/run_eval.py --ci --threshold 0.9
Validator cases require the HAPI sidecar (docker compose up hapi-validator).

Configuration

All settings via environment variables (see .env.example):

VariableDefaultDescription
FHIR_BASE_URLhttps://hapi.fhir.org/baseR4FHIR server base URL
HAPI_VALIDATOR_URLhttp://localhost:8082HAPI validator sidecar (runs on port 3500 internally; map 8082:3500)
FHIR_TIMEOUT_S30HTTP timeout in seconds
FHIR_MAX_RESULTS20Default _count for searches
MCP_TRANSPORTstdiostdio or sse
MCP_PORT8000Port for SSE transport
LOG_FORMATjsonjson (prod) or console (dev)
LANGFUSE_PUBLIC_KEY(unset)LangFuse observability (optional)
LANGFUSE_SECRET_KEY(unset)LangFuse observability (optional)

SMART-on-FHIR authentication

mcp-fhir v1.1.0 adds SMART-on-FHIR backend services (client_credentials grant, RFC 6749) so the server can authenticate against real Epic / Cerner sandboxes — no browser redirect needed.

When SMART_ENABLED=true, every FHIR request gets an Authorization: Bearer <token> header. Tokens are cached in-process and refreshed automatically 30 s before expiry.

SMART environment variables

VariableDefaultDescription
SMART_ENABLEDfalseSet true to activate SMART auth
SMART_CLIENT_ID""App client ID from EHR registration portal
SMART_CLIENT_SECRET""Client secret (stored as SecretStr, never logged)
SMART_TOKEN_URL""Token endpoint URL; auto-discovered if blank
SMART_SCOPESsystem/*.readSpace-separated OAuth 2.0 scopes
SMART_GRANT_TYPEclient_credentialsOAuth grant type (only client_credentials supported)
SMART_TOKEN_TIMEOUT_S15.0HTTP timeout for token requests

When SMART_TOKEN_URL is blank the server performs SMART auto-discovery:
GET {FHIR_BASE_URL}/.well-known/smart-configuration → token_endpoint.
Falls back to {FHIR_BASE_URL}/oauth2/token if discovery returns a non-200.

Epic sandbox quick-start

  1. Register at https://fhir.epic.com/ → My Apps → create a backend-services app.
  2. Note your Client ID and Client Secret.
  3. Create .env in the monorepo root (already in .gitignore):
dotenv
FHIR_BASE_URL=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4SMART_ENABLED=trueSMART_CLIENT_ID=your-epic-client-idSMART_CLIENT_SECRET=your-epic-client-secret# SMART_TOKEN_URL is optional — auto-discovered from FHIR_BASE_URL

Cerner sandbox quick-start

  1. Register at https://code.cerner.com/ → create a backend-services app.
  2. Note your Client ID and the token endpoint URL.
  3. Update .env:
dotenv
FHIR_BASE_URL=https://fhir-ehr-code.cerner.com/r4/your-tenant-idSMART_ENABLED=trueSMART_CLIENT_ID=your-cerner-client-idSMART_CLIENT_SECRET=your-cerner-client-secretSMART_TOKEN_URL=https://authorization.cerner.com/tenants/your-tenant-id/protocols/oauth2/profiles/smart-v1/token

Claude Desktop config with SMART auth

json
{  "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"      }    }  }}

Programmatic client (LangGraph / any Python agent)

Use StdioServerParameters to point any Python MCP client at a FHIR server. The same pattern works in LangGraph tool nodes, LangChain agents, or plain asyncio scripts.

python
from mcp import ClientSession, StdioServerParametersfrom mcp.client.stdio import stdio_clientimport 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())

See demo/fhir_server_configs.py for ready-to-run configs for all supported servers (public HAPI, SMART Health IT, Epic, Cerner, local Docker).

Running SMART integration tests

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

Profile validation

The validate_against_profile tool supports shorthand aliases:

AliasProfile URL
us-core-patienthttp://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
us-core-observationhttp://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-clinical-result
us-core-conditionhttp://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns
us-core-medication-requesthttp://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest
us-core-encounterhttp://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
ips-patienthttp://hl7.org/fhir/uv/ips/StructureDefinition/Patient-uv-ips

Profile validation requires the HAPI validator sidecar (included in docker-compose.yml at repo root).

Development

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

Architecture

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)

License

Apache-2.0

来源：packages/mcp-fhir/README.md，提交 07fc507

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.1.1最新Sep 16, 2026

评分

已满足适用检查项的 40%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。