Dicom MCP

🚀 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中設置服務器：

1. 在MCP Jam界面中點擊 訪客模式（無需賬戶）
2. 手動添加服務器，設置如下，或者導入 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中配置大語言模型：

1. 轉到 設置 選項卡
2. 添加你使用的大語言模型提供商的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密鑰）
3. 轉到 ** 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支持：用於模態工作列表和模態執行程序步驟跟蹤的表

設置步驟：

1. 啟動MySQL服務：

   docker compose up -d mysql
   

2. 初始化數據庫（首次啟動時自動執行，或手動執行）：

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

3. 在 .env 中配置環境變量：

   MINI_RIS_DB_PASSWORD=orthanc_ris_app
   

4. 驗證 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用戶的默認密碼

使用方法：

1. 啟動MWL/MPPS服務：

   docker compose up -d mwl-mpps mwl-api
   

2. 通過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
   

3. 通過REST API創建MWL條目：

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

4. 在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！

圖像生成模式：

1. simple（無需API密鑰） - 帶有解剖輪廓的基本合成圖像
2. ai（需要 OPENAI_API_KEY） - 通過OpenAI gpt - image - 1 模型生成逼真的AI圖像
3. auto（默認） - 如果有密鑰則使用AI，否則回退到簡單模式
4. 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服務器的推薦工具。

開發工作流：

1. 啟動Docker：docker-compose up -d
2. 加載測試數據：dotenv run -- pytest（上傳示例DICOM數據）
3. 啟動MCP Jam：npx -y @mcpjam/inspector@latest 或 npx -y @mcpjam/inspector@beta
4. 測試工具：使用工具選項卡交互式測試所有DICOM操作
5. 使用大語言模型測試：使用Playground選項卡測試自然語言交互
6. 調試問題：檢查服務器通知以獲取錯誤和詳細日誌

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文本提取。