fhir-mcp-server

🚀 FHIR MCP Server

FHIR MCP Server 实现了一个完整的模型上下文协议（MCP）服务器，旨在促进基于大语言模型（LLM）的代理与符合 FHIR 标准的后端之间的无缝交互。它提供了一个标准化接口，通过一套全面的工具实现对 FHIR 资源的完整 CRUD 操作，兼容 MCP 的客户端（如 Claude Desktop）可通过自然语言提示查询和操作临床数据。

🚀 快速开始

前提条件

• Docker（推荐）或 uv：用于依赖管理。 👉 uv 安装指南
• FHIR 服务器账户：具备访问 FHIR API 的权限（例如 Medplum）。
• Pinecone API 密钥（文档搜索必需）：支持对处理后的文档进行基于向量的搜索。若无此密钥，语义检索功能将无法使用。 👉 创建 Pinecone 账户
• LOINC 账户（可选）：可从官方 API 获取最新的 LOINC 代码。若无此账户，系统将依赖静态或语言模型推断的代码，这些代码可能过时或不准确。 👉 创建 LOINC 账户

安装与设置

1. 克隆仓库：

git clone https://github.com/the-momentum/fhir-mcp-server
cd fhir-mcp-server

2. 设置环境变量：

cp config/.env.example config/.env

编辑 config/.env 文件，填入你的凭证和配置。详情见环境变量。 3. 安装依赖

• 基于 Docker 执行：

make build

• 基于 uv 执行：

make uv

4. 更新 MCP 客户端配置
   • Docker

{
    "mcpServers": {
        "docker-mcp-server": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--init",
                "--mount", // 可选 - 用于重新加载的卷
                "type=bind,source=<your-project-path>/app,target=/root_project/app", // 可选 - 用于重新加载的卷
                "--mount",
                "type=bind,source=<your-project-path>/config/.env,target=/root_project/config/.env",
                "mcp-server:latest"
            ]
        }
    }
}

确保将 <your-project-path> 替换为你实际的安装路径。

• uv 首先，从终端获取 uv 路径：
  • Windows：

(Get-Command uv).Path

   - MacOS/Linux：

which uv

 然后，更新配置文件：

{
    "mcpServers": {
        "uv-mcp-server": {
            "command": "uv",
            "args": [
                "run",
                "--frozen",
                "--directory",
                "<your-project-path>",
                "start"
            ],
            "env": {
                "PATH": "<uv-bin-folder-path>"
            }
        }
    }
}

确保将 <uv-bin-folder-path> 替换为实际的 uv 路径（到 bin 文件夹）。 5. 重启 MCP 客户端 完成上述所有步骤后，重启 MCP 客户端以应用更改。在某些情况下，你可能需要使用任务管理器或系统的进程管理器终止所有相关进程。这可确保：

• 正确加载更新后的配置。
• 正确应用环境变量。
• FHIR MCP 客户端以正确的设置初始化。

(返回顶部)

✨ 主要特性

• 🚀 FastMCP 框架：基于 FastMCP 构建，具备高性能 MCP 服务器能力。
• 🏥 FHIR 资源管理：对所有主要 FHIR 资源进行完整的 CRUD 操作。
• 📄 智能文档处理：由人工智能驱动，支持 TXT、CSV、JSON 和 PDF 等多种格式的文档摄取和分块。
• 🔍 语义搜索：使用向量嵌入（通过 Pinecone）进行高级文档搜索。
• 🧠 支持 RAG：具备检索增强生成（RAG）管道，支持上下文感知的文档查询。
• 🔐 安全认证：通过 OAuth2 令牌管理实现 FHIR API 集成。
• 📊 LOINC 集成：支持标准化医学术语查找和验证。
• 🐳 支持容器化：支持 Docker，便于部署和扩展。
• 🔧 可配置：基于 .env 文件提供广泛的配置选项。

🏗️ 架构

服务器采用模块化架构构建：

• MCP 工具：为选定的 FHIR 资源类型提供专用工具，其他资源由通用工具处理。
• Fhir 服务器客户端：处理 FHIR API 通信和认证（OAuth2 等，更多认证方式计划中）。
• RAG 服务：基于嵌入的文档处理和语义检索。
• 向量存储：集成 Pinecone 实现基于相似度的搜索。
• LOINC 客户端：与 LOINC API 集成，实现术语解析和验证。

(返回顶部)

💡 演示

此演示展示了 Claude 如何使用 fhir-mcp-server 与 FHIR 服务器（此处为 Medplum）通信以回答问题。你将看到：

• 使用 request_patient_resource 工具检索患者基本信息。
• 使用 request_condition_resource 工具回答先前诊断的疾病是否会导致患者当前抱怨的症状。
• 使用 request_medication_resource、request_encounter_resource 和 request_generic_resource 工具回答患者是否已接受高血压治疗。

你可以观察到 Claude 如何根据用户查询自动选择合适的工具来回答问题。

演示视频链接

🔧 配置

环境变量

| 变量 | 描述 | 示例值 | |------|------|--------| | FHIR_SERVER_HOST | FHIR API 主机 URL | https://api.medplum.com | | FHIR_BASE_URL | FHIR 基础路径 | /fhir/R4 | | FHIR_SERVER_CLIENT_ID | FHIR 的 OAuth2 客户端 ID | 019720e7... | | FHIR_SERVER_CLIENT_SECRET | FHIR 的 OAuth2 客户端密钥 | 9e2ee73... | | LOINC_ENDPOINT | LOINC API 搜索端点 | https://loinc.regenstrief.org/searchapi/loincs | | LOINC_USERNAME | LOINC 账户用户名 | loinc-user | | LOINC_PASSWORD | LOINC 账户密码 | my-loinc-password | | PINECONE_API_KEY | Pinecone API 密钥 | pcsk_... | | EMBEDDING_MODEL | Hugging Face 嵌入模型名称 | NeuML/pubmedbert-base-embeddings |

(返回顶部)

🛠️ MCP 工具

FHIR MCP 服务器提供了一套全面的工具，用于与 FHIR 资源进行交互和文档管理：

FHIR 资源工具

| 工具 | 资源类型 | 描述 | |------|----------|------| | request_patient_resource | 患者 | 管理患者的人口统计和行政信息 | | request_observation_resource | 观察 | 处理临床测量和评估 | | request_condition_resource | 病情 | 管理患者的问题和诊断 | | request_medication_resource | 药物 | 处理药物信息和订单 | | request_immunization_resource | 免疫接种 | 管理疫苗接种记录 | | request_encounter_resource | 就诊 | 处理患者就诊和交互 | | request_allergy_intolerance_resource | 过敏不耐受 | 管理患者的过敏信息 | | request_family_member_history_resource | 家族成员病史 | 处理家族健康史 | | request_generic_resource | 任何 FHIR 资源 | 对特定工具未涵盖的任何 FHIR 资源进行操作 |

文档管理工具

| 工具 | 描述 | |------|------| | request_document_reference_resource | 管理 FHIR 文档引用资源 | | add_document_to_pinecone | 将文档导入向量数据库以进行语义搜索 | | search_pinecone | 使用向量嵌入对索引文档进行语义搜索 |

LOINC 术语工具

| 工具 | 描述 | |------|------| | get_loinc_codes | 检索医学观察和实验室测试的标准化 LOINC 代码 |

工具特性

• 全面的资源管理：所有 FHIR 资源工具支持创建、读取、更新和删除操作。
• 数据验证：工具强制执行 FHIR 资源验证，防止数据损坏。
• 错误处理：提供全面的错误响应，包含详细的失败信息。
• 安全保障：所有操作均支持 OAuth2 认证和适当的访问控制。
• 语义搜索：使用向量嵌入实现人工智能驱动的文档搜索。
• 多格式支持：文档摄取支持 TXT、PDF、CSV 和 JSON 格式。

(返回顶部)

🗺️ 路线图

我们正在不断为 FHIR MCP 服务器添加新功能。以下是即将推出的功能：

• [ ] 扩展认证选项：除了已支持的 OAuth2 之外，计划添加对其他连接 FHIR 服务器的认证方法的支持。
• [ ] 扩展 RAG 文件格式支持：扩展文档摄取功能，支持更多格式。
• [ ] 支持表格感知的文档分块：改进文档分块流程，检测文档中的表格并将其作为独立的原子块处理。
• [ ] 支持扫描文档的 OCR：实现光学字符识别（OCR）功能，以便在分块和索引之前从扫描的 PDF 和图像文件中提取文本。

如果你有建议，欢迎与我们联系或直接贡献代码！

👥 贡献者

(返回顶部)

📄 许可证

本项目采用 MIT 许可证进行分发。详情请参阅 MIT 许可证。