金大哥 - dicom-mcp MCP 详情

article

README

🚀 DICOM MCP服务器 - 医学影像AI集成 🏥

该项目使得AI助手能够使用标准的模型上下文协议（MCP），以Orthanc作为参考实现，在PACS上查询、读取和移动数据。你可以使用自己的API密钥（例如用于ChatGPT），并在开发时以ChatGPT作为大语言模型（LLM）在本地运行。此外，它还集成了FHIR和一个小型RIS数据库。

🚀 快速开始

📥 安装

通过克隆仓库并使用pip进行安装：

# 克隆并设置开发环境
gh repo clone sscotti/dicom-mcp
cd dicom-mcp

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -e ".[dev]"

⚙️ 配置

dicom-mcp 需要一个YAML配置文件（如 configuration.yaml）来定义DICOM节点和调用AE标题。你可以根据需要调整配置，或者保持默认配置以与示例ORTHANC服务器兼容。

# DICOM节点配置
nodes:
  main:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "本地Orthanc DICOM服务器（主服务器）"
  
  secondary:
    host: "localhost"
    port: 4243
    ae_title: "ORTHANC2"
    description: "本地Orthanc DICOM服务器（备用服务器）"

current_node: "main"
calling_aet: "MCPSCU"

# FHIR服务器配置（可选）
# 你可以配置多个FHIR服务器并在它们之间切换
fhir_servers:
  firely:
    base_url: "https://server.fire.ly"
    description: "Firely FHIR测试服务器（公共，无需API密钥）"
  
  siim:
    base_url: "https://hackathon.siim.org/fhir"
    api_key: "${SIIM_API_KEY}"  # 在.env文件中设置
    description: "SIIM黑客松FHIR服务器"
  
  # 取消注释以使用本地HAPI FHIR服务器
  hapi_local:
    base_url: "http://localhost:8080/fhir"
    description: "本地HAPI FHIR服务器"

current_fhir: "hapi_local"  # 活动的FHIR服务器：firely、siim或hapi_local，启动MCP服务器前请确保启动本地hapi fhir服务器

# 服务器将通过标准MCP协议公开所有DICOM工具和FHIR工具

# 小型RIS MySQL数据库配置（可选）
mini_ris:
  host: "localhost"
  port: 3306
  user: "orthanc_ris_app"
  password: "${MINI_RIS_DB_PASSWORD}"
  database: "orthanc_ris"
  pool_size: 5

⚠️ 重要提示

DICOM - MCP不适用于临床使用，不应连接到实时医院数据库或包含患者敏感数据的数据库。这样做可能导致患者数据丢失和患者数据泄露到互联网上。DICOM - MCP可以与本地托管的开源大语言模型一起使用，以实现完全的数据隐私。

💡 使用建议

本项目使用 MCP Jam 进行开发、测试和大语言模型集成。mcp - config.example.json 文件作为模板提供，其中包含相对路径，你可以根据自己的设置进行调整。该文件可以作为JSON导入到MCPJAM中以配置界面。

Docker容器设置（Orthancs、FHIR、PostGres和MySQL）

docker-compose up -d
dotenv run -- pytest # 上传虚拟PDF数据到ORTHANC服务器

UI访问地址：https://localhost:8042 和 https://localhost:8043，请注意，仓库配置了TLS证书，因此使用https。 HAPI FHIR访问地址：http://localhost:8080/fhir 详细的配置选项，包括Firely测试服务器和SIIM集成，请参阅 FHIR服务器指南。

🔌 与MCP Jam一起使用

MCP Jam 是测试和探索你的DICOM MCP服务器的推荐工具。它提供了一个带有 访客模式 的界面，无需任何设置即可立即进行测试。不过，你也可以在配置后使用类似Cursor IDE的工具。

启动MCP Jam：

# 导航到你的dicom - mcp目录
cd /path/to/dicom-mcp

# 激活你的虚拟环境
source venv/bin/activate

# 启动MCP Jam
npx -y @mcpjam/inspector@latest 或者 npx -y @mcpjam/inspector@beta

在MCP Jam中设置服务器：

在MCP Jam界面中点击 访客模式（无需账户）
手动添加服务器，设置如下，或者导入 mcp - config.example.json 作为模板：
- 服务器名称：DICOM MCP
- 命令：{path_to_venv}/bin/python（例如，venv/bin/python 或绝对路径）
- 参数：-m dicom_mcp configuration.yaml --transport stdio
- 环境变量：
  - 名称：PYTHONPATH
  - 值：src（相对路径）或 src 目录的绝对路径
- 工作目录：你的dicom - mcp项目根目录的路径

示例配置（macOS/Linux）：

命令：/absolute/path/to/dicom-mcp/venv/bin/python
参数：-m dicom_mcp configuration.yaml --transport stdio
环境变量：PYTHONPATH = /absolute/path/to/dicom-mcp/src

MCP Jam界面：

在MCP Jam中配置大语言模型：

转到设置选项卡
添加你使用的大语言模型提供商的API密钥：
- OpenAI - 用于GPT - 4、GPT - 4o、o1等
- Anthropic - 用于Claude 3.5 Sonnet、Claude Opus等
- Google Gemini - 用于Gemini 2.5 Pro、Flash等
- Deepseek - 用于Deepseek Chat、Reasoner
- Ollama - 自动检测本地模型（无需API密钥）
转到 ** playground** 选项卡，开始与你的DICOM服务器聊天

系统提示：为了更好地与大语言模型交互，你可以在MCP Jam的Playground选项卡中配置系统提示。system_prompt.txt 中提供了一个模板，在开始新会话时将其复制到系统提示字段中。

注意：MCP Jam访客模式可能不会在会话之间保留系统提示。请保留 system_prompt.txt 文件，以便在需要时进行复制粘贴。

MCP Jam功能：

✅ 访客模式：无需账户 - 立即开始测试
✅ 美观的用户界面：带有大语言模型提供商图标的现代界面
✅ 易于设置：通过清晰的表单进行简单的服务器配置
✅ 实时测试：交互式工具执行，即时获得结果
✅ 完整功能：访问所有11个DICOM工具
✅ 大语言模型Playground：使用各种大语言模型测试你的DICOM服务器
✅ 社区驱动：积极开发，定期更新

MCP Jam选项卡：

服务器选项卡：管理和连接到你的DICOM MCP服务器
工具选项卡：交互式浏览和测试所有11个DICOM工具
Playground选项卡：使用配置的大语言模型与你的DICOM服务器聊天
设置选项卡：配置API密钥和大语言模型提供商

可用的DICOM工具：

verify_connection - 测试DICOM连接
list_dicom_nodes - 显示配置的服务器
query_patients - 搜索患者
query_studies - 根据条件查找研究
query_series - 在研究中查找系列
query_instances - 查找单个DICOM图像
extract_pdf_text_from_dicom - 从DICOM PDF中提取文本
move_series / move_study - 传输DICOM数据
switch_dicom_node - 更改活动服务器
get_attribute_presets - 显示查询详细级别

可用的FHIR工具（当配置了FHIR时）：

verify_fhir_connection - 测试FHIR服务器连接
list_fhir_servers - 列出配置的FHIR服务器
fhir_search_patient - 搜索患者资源
fhir_search_imaging_study - 搜索影像研究资源
fhir_read_resource - 按类型和ID读取任何FHIR资源
fhir_create_resource - 创建新的FHIR资源（患者、影像研究、服务请求等）
fhir_update_resource - 更新现有的FHIR资源

详细配置请参阅FHIR_SERVERS.md。

小型RIS工具（当配置了MySQL时）：

list_mini_ris_patients - 浏览存储在小型RIS模式中的患者人口统计信息（按病历号或姓名过滤）
create_mwl_from_order - 根据现有的小型RIS订单创建DICOM模态工作列表条目
create_synthetic_cr_study - 生成合成的CR DICOM图像并发送到PACS（虚拟模态）

放射学报告工具（当配置了MySQL时）：

get_study_for_report - 检索用于放射学报告的完整研究信息
list_radiologists - 列出具有资质的可用放射科医生
create_radiology_report - 创建包含检查结果和印象的结构化放射学报告
generate_report_pdf - 从报告生成专业PDF（Base64编码）
attach_report_to_pacs - 将报告PDF作为DICOM封装PDF上传到PACS

小型RIS数据库模式： mini_ris.sql 模式提供了一个完整的放射学信息系统，包括：

核心实体：患者、提供者、会诊、订单、影像研究、报告
参考表：
- dicom_tags - 用于MWL/MPPS验证的50个基本DICOM标签定义
- procedures - 14个CR/XR程序代码，包含典型视图和图像数量
- modalities - 标准DICOM模态代码
- body_parts - 用于成像的解剖区域
MWL/MPPS支持：用于模态工作列表和模态执行程序步骤跟踪的表

设置步骤：

启动MySQL服务：
```
docker compose up -d mysql
```

初始化数据库（首次启动时自动执行，或手动执行）：

docker exec -i dicom-mcp-mysql-1 mysql -uorthanc_ris_app -porthanc_ris_app orthanc_ris < mysql/mini_ris.sql

在 .env 中配置环境变量：
```
MINI_RIS_DB_PASSWORD=orthanc_ris_app
```
验证 configuration.yaml 包含 mini_ris 块。

包含的CR程序：数据库包含14个常见的计算机放射摄影（CR）程序，针对单图像研究工作流程进行了优化：

胸部（1或2个视图）
腹部（1或2个视图）
骨盆、颈椎/腰椎
上肢：手、腕、肩
下肢：膝、踝、足
颅骨

每个程序包括典型的视图投影（前后位、后前位、侧位、斜位）和预期的图像数量，用于生成逼真的测试数据。

MWL/MPPS服务：项目包括集成的模态工作列表（MWL）和模态执行程序步骤（MPPS）服务，用于管理成像工作流程：

mwl - mpps（端口4104） - 用于MWL查询和MPPS N - CREATE/N - SET操作的DICOM SCP
mwl - api（端口8000） - 用于从小型RIS订单创建和管理MWL条目的FastAPI REST接口

环境变量：两个服务通过以下方式共享相同的MySQL数据库配置：

MINI_RIS_DB_PASSWORD=orthanc_ris_app  # orthanc_ris_app用户的默认密码

使用方法：

启动MWL/MPPS服务：
```
docker compose up -d mwl-mpps mwl-api
```

通过DICOM C - FIND查询工作列表：

# 使用 -W 进行模态工作列表查询（不是 -P 用于患者根）
findscu -v -W -k 0008,0050="" -k 0010,0020="" localhost 4104

# 或者按特定的访问号查询
findscu -v -W -k 0008,0050="ACC-2025-0001" localhost 4104

通过REST API创建MWL条目：

curl -X POST http://localhost:8000/mwl/create_from_json \
  -H "Content-Type: application/json" \
  -d @mwl_payload.json

在Web仪表板中查看MWL记录：

open http://localhost:8000/mwl
# 或者访问 http://localhost:8000 查看主仪表板

小型RIS数据库中的MWL/MPPS表（mwl、mpps、mwl_tasks）存储所有工作列表项和程序步骤状态，实现从订单到完成检查的完全可追溯性。

从订单创建MWL（通过MCP工具）： create_mwl_from_order 工具可自动从小型RIS订单创建MWL：

# 示例：患者到达，技术人员从订单创建MWL
# 在MCP Jam或通过大语言模型：
create_mwl_from_order(
    order_id=1,
    scheduled_station_aet="ORTHANC"
)

# 返回：
{
  "success": true,
  "message": "MWL为订单1成功创建",
  "accession_number": "ACC-2025-0001",
  "patient_name": "Alex Johnson",
  "patient_id": "MRN1001",
  "procedure": "胸部X光2视图",
  "modality": "CR",
  "scheduled_time": "2025-06-01 09:15:00",
  "mwl_id": 42
}

这支持基于大语言模型的工作流程，例如：

"为订单1创建工作列表条目"
"患者MRN1001已到达，为其安排胸部X光检查"
"列出所有预定订单，并为今天的患者创建MWL"

虚拟CR设备 🆕

项目包括一个虚拟CR（计算机放射摄影）设备，用于生成合成DICOM图像，以进行完整的工作流程演示：

# 示例：完整的成像工作流程
# 1. 从订单创建MWL
create_mwl_from_order(order_id=1)

# 2. 模拟CR设备采集图像
create_synthetic_cr_study(
    accession_number="ACC-2025-0001",
    image_mode="simple",  # 或者 "ai" 模式，需要OpenAI密钥
    send_to_pacs=True
)

# 结果：2张CR图像创建并发送到Orthanc！

图像生成模式：

simple（无需API密钥） - 带有解剖轮廓的基本合成图像
ai（需要 OPENAI_API_KEY） - 通过OpenAI gpt - image - 1 模型生成逼真的AI图像
auto（默认） - 如果有密钥则使用AI，否则回退到简单模式
sample - 使用库中的预先生成的样本图像

⚠️ 重要提示：

合成图像仅用于开发/测试/培训，不适用于临床使用。
AI模式使用OpenAI的 gpt - image - 1 模型（每张图像约30 - 40秒）
多视图研究（2张或更多图像）在MCP客户端中可能会超时，但 仍然会成功完成
- 即使看到超时错误，图像也会创建并发送到PACS
- 检查Orthanc以验证图像是否已到达
为了更快的生成或可靠的测试，请使用 image_mode="simple" 而不是 "auto"

配置：在 .env 中添加（AI模式可选）：

OPENAI_API_KEY=sk-proj-xxxxx  # 可选 - 启用AI生成的图像

基于大语言模型的工作流示例：

用户："患者Johnson完成了胸部X光检查，创建研究"
大语言模型：调用 create_synthetic_cr_study(accession_number="ACC-2025-0001", image_mode="simple")
结果：2视图胸部研究立即出现在Orthanc中！

用户："生成一张显示右肺肺炎的逼真胸部X光片"
大语言模型：以 image_mode="ai" 调用，image_description="右肺下叶肺炎"
结果：gpt - image - 1生成逼真的肺炎外观（约40秒）
注意：可能会显示超时错误，但图像仍会到达PACS

这完成了完整的RIS/PACS工作流程：

订单 → MWL → 虚拟设备 → DICOM图像 → PACS存储 → 查看 → 报告

放射学报告 🆕

创建专业的放射学报告，并将其作为DICOM封装PDF附加到PACS中的研究：

# 完整的报告工作流程
# 1. 获取报告所需的研究信息
study_info = get_study_for_report(accession_number="ACC-2025-0001")

# 2. 列出可用的放射科医生
radiologists = list_radiologists()

# 3. 创建放射学报告
report = create_radiology_report(
    accession_number="ACC-2025-0001",
    findings="""
    心脏大小正常。纵隔无异常。
    双肺清晰，无局灶性实变、胸腔积液或气胸。
    未发现急性骨骼异常。
    """,
    impression="正常胸部X光片。无急性心肺疾病。",
    author_provider_id=3,  # 来自 list_radiologists 的Dr. Casey Wells
    report_status="Final"
)

# 4. 生成PDF预览（可选）
pdf_data = generate_report_pdf(report_id=report['report_id'])
# 返回Base64编码的PDF，用于预览/下载

# 5. 将报告作为DICOM封装PDF附加到PACS
result = attach_report_to_pacs(report_id=report['report_id'])
# 报告PDF现在作为DOC系列出现在Orthanc中！

报告工作流功能：

数据库存储：报告保存在小型RIS reports 表中，具有完整的审计跟踪
专业PDF：使用ReportLab（默认）生成 - 包含机构标题、人口统计信息、检查结果、印象、签名
替代PDF库：WeasyPrint也作为选项安装，用于基于HTML/CSS的PDF生成（适用于基于Web的报告模板）
DICOM标准：封装PDF（SOP类：1.2.840.10008.5.1.4.1.1.104.1）
PACS集成：PDF作为新系列（模态：DOC，系列号9999）附加到原始研究
状态跟踪：初步 → 最终 → 修改 → 取消
提供者归属：链接到小型RIS提供者表中的放射科医生

基于大语言模型的报告示例：

用户："为访问号ACC-2025-0001创建最终报告。胸部X光正常。"
大语言模型：→ 调用 get_study_for_report() 获取患者/研究数据
     → 调用 list_radiologists() 获取可用的放射科医生
     → 调用 create_radiology_report() 创建结构化的检查结果/印象
     → 调用 attach_report_to_pacs() 将PDF发送到PACS
结果：数据库中完整的报告 + PACS中的PDF！

用户："为显示胫骨骨折的膝关节研究生成初步报告"
大语言模型：→ 创建报告，报告状态为 "Preliminary"
     → 结构化描述骨折的检查结果
     → 生成并将PDF附加到PACS
结果：可用于审核的初步报告

用户："显示报告ID 5的PDF"
大语言模型：→ 调用 generate_report_pdf(report_id=5)
     → 返回用于显示/下载的Base64编码的PDF

报告状态工作流：

初步 → 最终 → [修改] → [取消]

每次状态更改都会创建一个带有时间戳的新审计跟踪条目。

数据库模式：

reports:
  - report_id (主键)
  - imaging_study_id (外键，指向imaging_studies)
  - report_number (唯一，例如 "RPT-ACC-2025-0001-20250601120000")
  - author_provider_id (外键，指向providers - 放射科医生)
  - report_status (枚举：Preliminary, Final, Amended, Cancelled)
  - report_datetime (时间戳)
  - report_text (长文本 - 检查结果)
  - impression (文本 - 临床印象)
  - dicom_sop_instance_uid (在PACS附加后填充)
  - dicom_series_instance_uid (在PACS附加后填充)

完整的成像 + 报告工作流：

┌─────────────────────────────────────────────────────────┐
│ 1. 订单管理（小型RIS）                                 │
│    create_mwl_from_order(order_id=1)                    │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│ 2. 图像采集（虚拟CR设备）                              │
│    create_synthetic_cr_study(accession="ACC-2025-0001") │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│ 3. PACS存储（Orthanc）                                 │
│    图像可在 http://localhost:8042 查看                  │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│ 4. 放射学报告                                          │
│    create_radiology_report(...)                         │
│    attach_report_to_pacs(report_id=1)                   │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│ 5. PACS中完成的研究                                    │
│    - CR图像（系列1、2）                                 │
│    - 报告PDF（系列9999，模态DOC）                       │
└─────────────────────────────────────────────────────────┘

🧪 用于测试的合成数据

为了测试编排工作流程，使用合成数据填充本地HAPI FHIR服务器：

# 填充合成数据
python tests/populate_synthetic_fhir_data.py

这将创建：

5个具有真实人口统计信息的测试患者
影像研究的服务请求（订单）
与患者关联的影像研究
带有检查结果的诊断报告

🔄 编排工作流程

MCP服务器支持结合FHIR和DICOM的端到端放射学工作流程：

订单录入：在FHIR中创建服务请求
研究采集：将DICOM研究与FHIR影像研究关联
报告生成：从DICOM PDF生成诊断报告
工作流管理：跟踪订单直至完成

🔧 开发与调试

MCP Jam 是开发、测试和调试你的DICOM MCP服务器的推荐工具。

开发工作流：

启动Docker：docker-compose up -d
加载测试数据：dotenv run -- pytest（上传示例DICOM数据）
启动MCP Jam：npx -y @mcpjam/inspector@latest 或 npx -y @mcpjam/inspector@beta
测试工具：使用工具选项卡交互式测试所有DICOM操作
使用大语言模型测试：使用Playground选项卡测试自然语言交互
调试问题：检查服务器通知以获取错误和详细日志

MCP Jam在开发中的优势：

✅ 访客模式 - 无需账户，立即使用
✅ 实时测试 所有DICOM工具，即时反馈
✅ 交互式界面 用于探索DICOM数据和响应
✅ 大语言模型集成 - 测试AI助手与服务器的交互
✅ 调试日志 - 查看详细的服务器通知和错误
✅ 工具浏览器 - 轻松发现和测试所有可用工具

✨ 主要特性

dicom - mcp 提供以下工具：

🔍 查询Orthanc：使用各种标准搜索患者、研究、系列和实例。
📄 读取DICOM报告（PDF）：检索包含封装PDF（例如临床报告）的DICOM实例，并提取文本内容。
📄 创建RIS和DICOM报告（PDF）：创建PDF格式的示例报告。
➡️ 发送DICOM图像：将系列或研究发送到其他DICOM目的地，例如用于图像分割、分类等的AI端点。
⚙️ 实用工具：管理连接并了解查询选项。
⚙️ FHIR方法：提供与FHIR相关的操作。
⚙️ 小型RIS：具备小型放射学信息系统的功能。
⚙️ MWL服务器：支持模态工作列表相关操作。

📄 许可证

本项目采用 MIT许可证。

🙏 致谢

使用 pynetdicom 构建。
使用 PyPDF2 进行PDF文本提取。

dicom-mcp