FHIR-MCP服务器
项目介绍
快速医疗互操作资源（FHIR）API的模型上下文协议（MCP）服务器
目录
概述
FHIR MCP服务器是一个模型上下文协议（MCP）服务器，它提供了与FHIR API的无缝集成。该服务器设计用于开发者、集成商和医疗创新者，作为现代AI/LLM工具与医疗数据之间的桥梁，使得搜索、检索和分析临床信息变得容易。
演示
与HAPI FHIR服务器的演示
此视频展示了当连接到公共HAPI FHIR服务器时，MCP服务器的功能。此示例展示了直接与一个不需要授权流程的开放FHIR服务器进行交互。
https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf
与EPIC沙盒的演示
此视频展示了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服务器和客户端进行身份验证
- 工具集成：可以与任何MCP客户端集成，如VS Code、Claude Desktop和MCP Inspector
先决条件
- Python 3.8+
- uv（用于依赖管理）
- 可访问的FHIR API服务器。
安装
您可以通过安装我们的Python包或克隆此仓库来使用FHIR MCP服务器。
使用PyPI包安装
-
配置环境变量：
要运行服务器，您必须设置
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" - 启用授权：设置
-
安装PyPI包并运行服务器
uvx fhir-mcp-server
从源码安装
-
克隆仓库：
git clone <repository_url> cd <repository_directory> -
创建虚拟环境并安装依赖项：
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 -
配置环境变量： 复制示例文件并根据需要自定义：
cp .env.example .env -
运行服务器：
uv run fhir-mcp-server
使用Docker安装
使用Docker运行MCP服务器
您可以使用Docker运行MCP服务器以获得一致且隔离的环境。
关于授权：当通过Docker或Docker Compose本地运行MCP服务器时，应通过设置环境变量
FHIR_SERVER_DISABLE_AUTHORIZATION=True来禁用授权。这将在未来的发布中得到解决。
-
构建Docker镜像或从容器注册表拉取镜像：
- 从源码构建：
docker build -t fhir-mcp-server . - 从GitHub容器注册表拉取：
docker pull wso2/fhir-mcp-server:latest
- 从源码构建：
-
配置环境变量
复制示例环境文件并根据需要编辑：
cp .env.example .env # 编辑.env以设置您的FHIR服务器、客户端凭证等。或者，您可以直接使用
-e标志传递环境变量，或使用Docker密钥存储敏感值。详情请参阅配置部分。 -
运行容器
docker run --env-file .env -p 8000:8000 fhir-mcp-server这将启动服务器并在端口8000上公开。根据需要调整端口映射。
使用Docker Compose与HAPI FHIR服务器
为了快速设置包括FHIR MCP服务器和HAPI FHIR服务器（带PostgreSQL）的环境，请使用提供的docker-compose.yml。这将设置一个即时开发环境，用于测试FHIR操作。
-
先决条件：
- 已安装Docker和Docker Compose。
-
运行堆栈：
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。
-
访问服务：
- FHIR MCP服务器：http://localhost:8000
- HAPI FHIR服务器：http://localhost:8080
- 停止运行
docker-compose down。
-
配置其他环境变量：
如果需要自定义OAuth或其他设置，请调整
docker-compose.yml中的环境变量。组合文件设置了基本配置；请参阅配置部分了解全部选项。
与MCP客户端集成
FHIR MCP服务器旨在与各种MCP客户端无缝集成。
VS Code
在VS Code的用户设置（JSON）文件中添加以下JSON块（> V1.101）。您可以通过按Ctrl + Shift + P并键入“Preferences: Open User Settings (JSON)”来完成此操作。
<table> <tr><th>可流式传输的HTTP</th><th>STDIO</th><th>SSE</th></tr> <tr valign=top> <td>"mcp": {
"servers": {
"fhir": {
"type": "http",
"url": "http://localhost:8000/mcp",
}
}
}
"mcp": {
"servers": {
"fhir": {
"command": "uv",
"args": [
"--directory",
"/path/to/fhir-mcp-server",
"run",
"fhir-mcp-server",
"--transport",
"stdio"
],
"env": {
"FHIR_SERVER_ACCESS_TOKEN": "您的FHIR访问令牌"
}
}
}
}
"mcp": {
"servers": {
"fhir": {
"type": "sse",
"url": "http://localhost:8000/sse",
}
}
}
Claude Desktop
在Claude Desktop设置中添加以下JSON块以连接到本地MCP服务器。
- 打开Claude Desktop应用程序，在顶部栏点击Claude菜单，然后选择“设置…”。
- 在设置面板中，点击左侧边栏的“开发者”，然后点击“编辑配置”。这将在您的文件系统中打开配置文件。如果尚未存在，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": "您的FHIR访问令牌"
}
}
}
}
{
"mcpServers": {
"fhir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/sse"
]
}
}
}
MCP Inspector
按照以下步骤启动并运行MCP Inspector：
-
打开终端并运行以下命令：
npx -y @modelcontextprotocol/inspector -
在MCP Inspector界面中：
- 传输类型：
可流式传输的HTTP - URL：
http://localhost:8000/mcp
- 传输类型：
STDIO - 命令：
uv - 参数：
--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio
- 传输类型：
SSE - URL：
http://localhost:8000/sse
确保您的MCP服务器已经在上述端点上运行并监听。
一旦连接，MCP Inspector将允许您可视化工具调用，检查请求/响应负载，并轻松调试工具实现。
配置
CLI选项
您可以使用以下命令行标志来自定义MCP服务器的行为：
-
--transport
- 描述：指定MCP服务器与客户端通信所使用的传输协议。
- 接受值：stdio, sse, 可流式传输的HTTP
- 默认值：可流式传输的HTTP
-
--log-level
- 描述：设置服务器的日志详细程度。
- 接受值：DEBUG, INFO, WARN, ERROR（不区分大小写）
- 默认值：INFO
-
--help
- 描述：显示带有可用服务器选项的帮助消息并退出。
- 使用：由命令行接口自动提供。
示例用法：
uv run fhir-mcp-server --transport 可流式传输的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配置或位于代理之后的情况很有用。FHIR_MCP_REQUEST_TIMEOUT：MCP服务器向FHIR服务器发出请求的超时时间（默认：30秒）。
MCP服务器OAuth2与FHIR服务器配置（MCP客户端 ↔ MCP服务器）： 这些变量配置了MCP客户端与MCP服务器的安全连接，使用OAuth2授权码授予流程与FHIR服务器。
FHIR_SERVER_CLIENT_ID：用于授权MCP客户端与FHIR服务器的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授权流程，并直接使用此令牌进行所有请求。
工具
-
get_capabilities：检索指定FHIR资源类型的元数据，包括其支持的搜索参数和自定义操作。type：FHIR资源类型名称（例如，“Patient”，“Observation”，“Encounter”）
-
search：在给定资源类型上执行标准FHIR搜索交互，返回匹配资源的捆绑包或列表。type：FHIR资源类型名称（例如，“MedicationRequest”，“Condition”，“Procedure”）。searchParam：FHIR搜索参数名称及其期望值的映射（例如，{"family":"Simpson","birthdate":"1956-05-