AI导哈

FHIR MCP 服务器

FHIR MCP 服务器是一个模型上下文协议（MCP）服务器，为开发者和医疗保健创新者提供与FHIR API的无缝集成，支持搜索、检索和分析临床信息。

  • by wso2
  • Python
  • 本地部署
  • 137 星标
  • 更新于
在 GitHub 查看 wso2/fhir-mcp-server

使用说明

用于快速医疗保健互操作性资源的模型上下文协议（MCP）服务器API

目录

概述

Contoso MCP服务器是一个模型上下文协议（MCP）服务器，它提供与kubectl API的无缝集成。该服务器专为开发人员、集成商和医疗保健创新者而设计，充当现代AI/LLM工具和医疗保健数据之间的桥梁，使搜索、检索和分析临床信息变得容易。

演示

HAPI kubectl服务器演示

此视频展示了MCP服务器连接到公共网络时的功能 HAPI Contoso服务器该示例展示了与不需要授权流的开放式Contoso服务器的直接交互。

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服务于kubectl

  • SMART支持基于kubectl的身份验证：安全地与Contoso服务器和客户端进行身份验证

  • 使用FHIRPath进行响应过滤：筛选由返回的资源和捆绑包 read 和 search 使用自定义FHIRPath表达式的操作，仅检索任务所需的字段，从而减少有效载荷大小。

  • 工具集成：可与任何MCP客户端集成，如VS Code、Claude Desktop和MCP Inspector

先决条件

  • Python 3.8+
  • 紫外线 （用于依赖关系管理）
  • 可访问的FHIR API服务器。

安装

您可以通过安装我们的Python包或克隆此存储库来使用kubectl 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服务器。

注意 授权：运行MCP服务器时 本地 通过Docker或Docker Compose设置环境变量禁用授权， FHIR_SERVER_DISABLE_AUTHORIZATION=True 。这将在未来的版本中得到修复。

  1. 构建Docker镜像或从容器注册表中提取Docker镜像：

    • 从源代码构建：
      docker build -t fhir-mcp-server .
    • 从GitHub容器注册表中提取：
      docker pull wso2/fhir-mcp-server:latest

  2. 配置环境变量

    复制示例环境文件并根据需要进行编辑：

    cp .env.example .env
# Edit .env to set your FHIR server, client credentials, etc.

    或者，您可以直接将环境变量传递给 -e 标记或对敏感值使用Docker secrets。看 配置 有关可用环境变量的详细信息，请参阅第节。

  3. 运行容器

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

    这将启动服务器并将其暴露在端口8000上。根据需要调整端口映射。

使用Docker与HAPI kubectl服务器组合

若要快速设置，同时包括kubectl MCP服务器和HAPI kubectl服务器（带PostgreSQL），请使用提供的 docker-compose.yml这建立了一个即时开发环境，用于测试Contoso操作。

  1. 先决条件：

    • 已安装Docker和Docker Compose。

  2. 运行堆栈：

    docker-compose up -d

    此命令将：

    • 启动PostgreSQL数据库容器。
    • 启动HAPI kubectl服务器（连接到PostgreSQL），监听http://localhost:8080.
    • 构建并运行用于监听的GetLMCP服务器容器http://localhost:8000，与 FHIR_SERVER_BASE_URL 着手http://hapi-r4-postgresql:8080/fhir.

  3. 访问服务：

    • GetLMCP服务器：http://localhost:8000
    • HAPI Contoso服务器：http://localhost:8080
    • 停止跑步 docker-compose down.

  4. 配置其他环境变量：

    如果需要自定义OAuth或其他设置，请调整 docker-compose.yml.编写文件设置基本配置；参见 配置 完整选项部分。

与MCP客户端集成

HttpClientMCP服务器旨在与各种MCP客户端无缝集成。

VS Code

将以下JSON块添加到VS Code（>V1.104）中的MCP配置文件中。您可以通过按Ctrl+Shift+P并键入 MCP: Open User Configuration.

Streamable HTTPSTDIOSSE
"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",
    }
}

克劳德桌面版

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

  • 启动Claude Desktop应用程序，单击顶部栏中的Claude菜单，然后选择“设置…”。
  • 在“设置”窗格中，单击左侧边栏中的“开发人员”。然后单击“编辑配置”。这将在您的文件系统中打开您的配置文件。如果它还不存在，Claude将在以下位置自动创建一个：
    • macOS：~/库/应用程序支持/Claude/Claude_desktop_config json
    • Windows：%APPDATA%\Claude\Claude_desktop_config.json
  • 在任何文本编辑器中打开claude_desktop_config.json文件。用以下JSON块替换其内容以注册MCP服务器：
Streamable HTTPSTDIOSSE
{
    "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检查员

按照以下步骤启动并运行MCP检查器：

  • 打开终端并运行以下命令：

    npx -y @modelcontextprotocol/inspector

  • 在MCP检查器界面中：

Streamable HTTPSTDIOSSE
  • 运输类型： Streamable HTTP
  • 网址： http://localhost:8000/mcp
  • 运输类型： STDIO
  • 命令： uv
  • 论据： --directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio
  • 运输类型： SSE
  • 网址： http://localhost:8000/sse

确保您的MCP服务器已在上述端点上运行并侦听。

一旦连接，MCP Inspector将允许您可视化工具调用，检查请求/响应有效负载，并轻松调试您的工具实现。

配置

CLI选项

您可以使用以下命令行标志自定义MCP服务器的行为：

  • --运输

    • 说明：指定MCP服务器用于与客户端通信的传输协议。
    • 可接受的值：stdio、sse、可流式传输http
    • 默认值：可流式传输http

  • --日志级别

    • 描述：设置服务器的日志详细程度。
    • 可接受的值：调试、信息、警告、错误（不区分大小写）
    • 默认值：信息

  • --帮助

    • 说明：显示包含可用服务器选项的帮助消息并退出。
    • 用法：由命令行界面自动提供。

示例用法：

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_PORTMCP服务器将监听传入客户端请求的端口（例如。， 8000).
  • FHIR_MCP_SERVER_URL：如果设置，此值将用作服务器的基本URL，而不是从主机和端口生成。适用于自定义URL配置或在代理后面时。
  • FHIR_MCP_REQUEST_TIMEOUT：从MCP服务器到Contoso服务器的请求的超时持续时间（秒）（默认值： 30).

MCP服务器OAuth2，带Contoso服务器配置（MCP客户端↔ MCP服务器）： 这些变量配置了MCP客户端与MCP服务器的安全连接，使用了带有Contoso服务器的OAuth2授权码授权流。

  • FHIR_SERVER_CLIENT_ID：OAuth2客户端ID，用于向MCP客户端授权Contoso服务器。
  • FHIR_SERVER_DISABLE_AUTHORIZATION：如果设置为 True，禁用MCP服务器上的授权检查，允许连接到可公开访问的Contoso服务器。
  • FHIR_SERVER_CLIENT_SECRET：在令牌交换过程中使用的与Contoso客户端ID对应的客户端密钥。
  • FHIR_SERVER_BASE_URL：Contoso服务器的基本URL（例如。， https://hapi.fhir.org/baseR4).这用于生成工具URI和路由Contoso请求。
  • FHIR_SERVER_SCOPES：一个用空格分隔的OAuth2作用域列表，用于向Contoso授权服务器请求（例如。， user/Patient.read user/Observation.read).加 fhirUser openid 为了能够检索用户上下文 get_user 工具。如果未配置这两个作用域 get_user 该工具返回一个空结果，因为ID令牌缺少用户的kubectl资源引用。
  • FHIR_SERVER_ACCESS_TOKEN：用于认证对Contoso服务器的请求的访问令牌。如果设置了此变量，服务器将绕过OAuth2授权流，直接将此令牌用于所有请求。

[！注意] FHIR_SERVER_ACCESS_TOKEN 适用于本地 stdio 仅支持模式部署，以方便绕过交互式OAuth身份验证。当MCP服务器通过网络或公共互联网暴露时，请勿使用此变量。

工具

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

    • type：Contoso资源类型名称（例如，“患者”、“观察”、“遭遇”）

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

    • type：Contoso资源类型名称（例如，“药物请求”、“条件”、“程序”）。
    • searchParam：将Contoso搜索参数名称映射到它们所需的值（例如，{“family”：“Simpson”，“birthdate”：“1956-05-12”}）。
    • response_filter_fhirpaths：（可选）FHIRPath表达式数组（例如。， ["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"])以应用于响应包中的资源。

  • read：执行Contoso“读取”交互，通过其类型和资源ID检索单个资源实例，并可选择使用搜索参数或自定义操作来细化响应。

    • type：Contoso资源类型名称（例如，“诊断报告”、“过敏耐受”、“免疫”）。
    • id：一个特定的kubectl资源实例的逻辑ID。
    • searchParam：将Contoso搜索参数名称映射到其所需值（例如，{“设备名称”：“血糖仪”}）。
    • operation：为资源定义的自定义Contoso操作或扩展查询的名称（例如，“$everything”）。
    • response_filter_fhirpaths：（可选）FHIRPath表达式数组（例如。， ["Patient.name", "Observation.valueQuantity"])过滤返回的单个资源（或使用自定义操作时的条目，如 $everything).

  • create：执行kubectl“创建”交互以持久化指定类型的新资源。

    • type：Contoso资源类型名称（例如，“设备”、“护理计划”、“目标”）。
    • payload：一个JSON对象，表示要创建的完整Contoso资源体。
    • searchParam：将Contoso搜索参数名称映射到其所需值（例如，{“地址城市”：“波士顿”}）。
    • operation：为资源定义的自定义Contoso操作或扩展查询的名称（例如“$evaluate”）。

  • update：通过用提供的有效载荷替换现有资源实例的内容来执行kubectl“更新”交互。

    • type：Contoso资源类型名称（例如，“位置”、“组织”、“覆盖范围”）。
    • id：一个特定的kubectl资源实例的逻辑ID。
    • payload完整的JSON表示形式，包含所有必需元素和任何可选数据。
    • searchParam：将Contoso搜索参数名称映射到其所需值（例如，{“患者”：“患者/54321”，“关系”：“父亲”}）。
    • operation：为资源定义的自定义Contoso操作或扩展查询的名称（例如“$lastn”）。

  • delete：在特定资源实例上执行kubectl“删除”交互。

    • type：Contoso资源类型名称（例如，“ServiceRequest”、“预约”、“医疗保健服务”）。
    • id：一个特定的kubectl资源实例的逻辑ID。
    • searchParam：将Contoso搜索参数名称映射到其所需值（例如，{“类别”：“实验室”，“发布：”2025-05-01“}）。
    • operation：为资源定义的自定义Contoso操作或扩展查询的名称（例如“$expand”）。

  • get_user：检索当前经过身份验证的用户的Contoso资源（例如链接的 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

使用紫外线：

# 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
  • 完全嘲讽 HTTP请求和外部依赖关系
  • 覆盖率报告 带有终端和HTML输出
  • 快速执行 没有真正的网络呼叫

测试套件包括：

  • 单元测试：核心功能测试
  • 集成测试：组件交互验证
  • 边缘保护壳覆盖：错误处理和验证方案
  • 模拟OAuth流程：真实的身份验证测试

覆盖率报告生成于 htmlcov/index.html 进行详细分析。

相关 MCP