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 服务
      • 将 Docker Compose 与 HAPI FHIR 服务搭配使用
  • 与 MCP 客户端集成
    • VS Code
    • Claude Desktop
    • MCP Inspector
  • 配置
    • CLI 选项
    • 环境变量
  • 工具
  • 开发与测试
    • 安装开发依赖项
    • 运行测试

概述

FHIR MCP 服务是一种 Model Context Protocol (MCP) 服务，可与 FHIR API 无缝集成。该服务面向开发者、集成者和医疗创新者，充当现代 AI/大模型工具与医疗数据之间的桥梁，让您能够轻松搜索、检索和分析临床信息。

演示

使用 HAPI FHIR 服务演示

此视频展示了 MCP 服务连接到公共 HAPI FHIR 服务时的功能。示例演示了与无需授权流程的开放 FHIR 服务直接交互。

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

使用 EPIC Sandbox 演示

此视频展示了 MCP 服务在 Epic EHR 生态系统中的功能，并演示了完整的 OAuth 2.0 授权码授予流程。

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

核心功能

• 兼容 MCP 的传输方式：通过 stdio、SSE 或可流式传输的 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 服务。

使用 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 服务

您可以使用 Docker 运行 MCP 服务，以获得一致且隔离的环境。

关于 授权 的说明：通过 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
   # 编辑 .env 以设置 FHIR 服务、客户端凭据等。
   

   或者，您可以直接使用 -e 标志传递环境变量，也可以使用 Docker secrets 存储敏感值。有关可用环境变量的详细信息，请参阅配置部分。

3. 运行容器

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

   这将启动服务并在端口 8000 上公开服务。请根据需要调整端口映射。

使用 Docker Compose 搭配 HAPI FHIR Server

如需快速设置同时包含 FHIR MCP 服务和 HAPI FHIR 服务（使用 PostgreSQL）的环境，请使用提供的 docker-compose.yml。这将搭建一个即时开发环境，用于测试 FHIR 操作。

1. 前提条件：

   • 已安装 Docker 和 Docker Compose。

2. 运行服务栈：

   docker-compose up -d
   

   此命令将：

   • 启动 PostgreSQL 数据库容器。
   • 启动 HAPI FHIR 服务（连接到 PostgreSQL），并在 http://localhost:8080 上监听。
   • 构建并运行 FHIR MCP 服务容器，并在 http://localhost:8000 上监听，同时将 FHIR_SERVER_BASE_URL 设置为 http://hapi-r4-postgresql:8080/fhir。

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

将以下 JSON 代码块添加到 VS Code（> V1.104）的 MCP 配置文件中。你可以按 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

将以下 JSON 代码块添加到 Claude Desktop 设置中，以连接到本地 MCP 服务。

• 启动 Claude Desktop 应用，点击顶部栏中的 Claude 菜单，然后选择“Settings…”。
• 在 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 文件。将其内容替换为以下 JSON 代码块，以注册 MCP 服务：

{
    "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）。

MCP 服务与 FHIR 服务之间的 OAuth2 配置（MCP 客户端 ↔ MCP 服务）： 这些变量用于配置 MCP 客户端与 MCP 服务之间的安全连接，该连接使用与 FHIR 服务配合的 OAuth2 授权码授权流程。

• 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）。添加 fhirUser openid 可为 get_user 工具启用用户上下文检索。如果未配置这两个作用域，get_user 工具将返回空结果，因为 ID 令牌中不包含用户的 FHIR 资源引用。
• FHIR_SERVER_ACCESS_TOKEN：用于验证发往 FHIR 服务的请求的访问令牌。如果设置此变量，服务将跳过 OAuth2 授权流程，并在所有请求中直接使用此令牌。

说明

FHIR_SERVER_ACCESS_TOKEN 仅适用于本地 stdio 模式部署，用作跳过交互式 OAuth 身份验证的便捷方式。当 MCP 服务通过网络或公共互联网对外开放时，请勿使用此变量。

工具

• get_capabilities：检索指定 FHIR 资源类型的元数据，包括其支持的搜索参数和自定义操作。

  • type：FHIR 资源类型名称（例如，“Patient”“Observation”“Encounter”）。

• search：对给定资源类型执行标准 FHIR 搜索交互，并返回匹配资源的 Bundle 或列表。

  • type：FHIR 资源类型名称（例如，“MedicationRequest”“Condition”“Procedure”）。
  • searchParam：将 FHIR 搜索参数名称映射到所需值（例如，{"family":"Simpson","birthdate":"1956-05-12"}）。
  • response_filter_fhirpaths：（可选）要应用于响应 Bundle 中资源的 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”交互，使用提供的 payload 替换现有资源实例的内容。

  • 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，供详细分析。