dicom-mcp: 一个 DICOM 模型上下文协议服务器

此仓库是博客文章的一部分：代理医疗 LLMs

概述

这是一个用于 DICOM（医学数字成像和通信）交互的模型上下文协议服务器。该服务器提供了查询和与 DICOM 服务器交互的工具，使大型语言模型能够访问和分析医学影像元数据。

dicom-mcp 允许 AI 助手使用标准的 DICOM 网络协议从 DICOM 服务器查询患者信息、研究、序列和实例。它还支持从存储在 DICOM 格式中的封装 PDF 文档中提取文本，从而可以分析临床报告。它是基于 pynetdicom 构建的，并遵循模型上下文协议规范。

工具

1. list_dicom_nodes

   • Lists all configured DICOM nodes and calling AE titles
   • Inputs: None
   • Returns: Current node, available nodes, current calling AE title, and available calling AE titles

2. switch_dicom_node

   • Switches to a different configured DICOM node
   • Inputs:
     • node_name (string): Name of the node to switch to
   • Returns: Success message

3. switch_calling_aet

   • Switches to a different configured calling AE title
   • Inputs:
     • aet_name (string): Name of the calling AE title to switch to
   • Returns: Success message

4. verify_connection

   • Tests connectivity to the configured DICOM node using C-ECHO
   • Inputs: None
   • Returns: Success or failure message with details

5. query_patients

   • Search for patients matching specified criteria
   • Inputs:
     • name_pattern (string, optional): Patient name pattern (can include wildcards)
     • patient_id (string, optional): Patient ID
     • birth_date (string, optional): Patient birth date (YYYYMMDD)
     • attribute_preset (string, optional): Preset level of detail (minimal, standard, extended)
     • additional_attributes (string[], optional): Additional DICOM attributes to include
     • exclude_attributes (string[], optional): DICOM attributes to exclude
   • Returns: Array of matching patient records

6. query_studies

   • Search for studies matching specified criteria
   • Inputs:
     • patient_id (string, optional): Patient ID
     • study_date (string, optional): Study date or range (YYYYMMDD or YYYYMMDD-YYYYMMDD)
     • modality_in_study (string, optional): Modalities in study
     • study_description (string, optional): Study description (can include wildcards)
     • accession_number (string, optional): Accession number
     • study_instance_uid (string, optional): Study Instance UID
     • attribute_preset (string, optional): Preset level of detail
     • additional_attributes (string[], optional): Additional DICOM attributes to include
     • exclude_attributes (string[], optional): DICOM attributes to exclude
   • Returns: Array of matching study records

7. query_series

   • Search for series within a study
   • Inputs:
     • study_instance_uid (string): Study Instance UID (required)
     • modality (string, optional): Modality (e.g., "CT", "MR")
     • series_number (string, optional): Series number
     • series_description (string, optional): Series description
     • series_instance_uid (string, optional): Series Instance UID
     • attribute_preset (string, optional): Preset level of detail
     • additional_attributes (string[], optional): Additional DICOM attributes to include
     • exclude_attributes (string[], optional): DICOM attributes to exclude
   • Returns: Array of matching series records

8. query_instances

   • Search for instances within a series
   • Inputs:
     • series_instance_uid (string): Series Instance UID (required)
     • instance_number (string, optional): Instance number
     • sop_instance_uid (string, optional): SOP Instance UID
     • attribute_preset (string, optional): Preset level of detail
     • additional_attributes (string[], optional): Additional DICOM attributes to include
     • exclude_attributes (string[], optional): DICOM attributes to exclude
   • Returns: Array of matching instance records

9. get_attribute_presets

   • Lists available attribute presets for queries
   • Inputs: None
   • Returns: Dictionary of available presets and their attributes by level

10. retrieve_instance

    • Retrieves a specific DICOM instance and saves it to the local filesystem
    • Inputs:
      • study_instance_uid (string): Study Instance UID
      • series_instance_uid (string): Series Instance UID
      • sop_instance_uid (string): SOP Instance UID
      • output_directory (string, optional): Directory to save the retrieved instance to (default: "./retrieved_files")
    • Returns: Dictionary with information about the retrieval operation

11. extract_pdf_text_from_dicom

    • Retrieves a DICOM instance containing an encapsulated PDF and extracts its text content
    • Inputs:
      • study_instance_uid (string): Study Instance UID
      • series_instance_uid (string): Series Instance UID
      • sop_instance_uid (string): SOP Instance UID
    • Returns: Dictionary with extracted text information and status

安装

前提条件

• Python 3.12 或更高版本
• 一个 DICOM 服务器以进行连接（例如，Orthanc, dcm4chee 等）

使用 pip

通过 pip 安装：

pip install dicom-mcp

配置

dicom-mcp 需要一个 YAML 配置文件来定义 DICOM 节点和调用 AE 标题。创建一个具有以下结构的配置文件：

# DICOM nodes configuration
nodes:
  orthanc:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server"
  
  clinical:
    host: "pacs.hospital.org"
    port: 11112
    ae_title: "CLIN_PACS"
    description: "Clinical PACS server"

# Local calling AE titles
calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE title"
  
  modality:
    ae_title: "MODALITY"
    description: "Simulating a modality"

# Currently selected node
current_node: "orthanc"

# Currently selected calling AE title
current_calling_aet: "default"

使用

命令行

使用脚本入口点运行服务器：

dicom-mcp /path/to/configuration.yaml

如果使用 uv：

uv run dicom-mcp /path/to/configuration.yaml

与 Claude Desktop 配置

在 claude_desktop_config.json 中添加以下内容：

"mcpServers": {
  "dicom": {
    "command": "uv",
    "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
  }
}

与 Zed 一起使用

在 Zed 的 settings.json 中添加以下内容：

"context_servers": [
  "dicom-mcp": {
    "command": {
      "path": "uv",
      "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
    }
  }
],

示例查询

列出可用的 DICOM 节点

list_dicom_nodes()

切换到不同的节点

switch_dicom_node(node_name="clinical")

切换到不同的调用 AE 标题

switch_calling_aet(aet_name="modality")

验证连接

verify_connection()

搜索患者

# Search by name pattern (using wildcard)
patients = query_patients(name_pattern="SMITH*")

# Search by patient ID
patients = query_patients(patient_id="12345678")

# Get detailed information
patients = query_patients(patient_id="12345678", attribute_preset="extended")

搜索研究

# Find all studies for a patient
studies = query_studies(patient_id="12345678")

# Find studies within a date range
studies = query_studies(study_date="20230101-20231231")

# Find studies by modality
studies = query_studies(modality_in_study="CT")

在研究中搜索序列

# Find all series in a study
series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1")

# Find series by modality and description
series = query_series(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    modality="CT",
    series_description="CHEST*"
)

在序列中搜索实例

# Find all instances in a series
instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2")

# Find a specific instance by number
instances = query_instances(
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    instance_number="1"
)

检索 DICOM 实例

# Retrieve a specific instance
result = retrieve_instance(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.3",
    output_directory="./dicom_files"
)

从 DICOM 封装的 PDF 中提取文本

# Extract text from an encapsulated PDF
result = extract_pdf_text_from_dicom(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.3"
)

调试

可以使用 MCP 检查器来调试服务器：

npx @modelcontextprotocol/inspector uv --directory /path/to/dicom-mcp run dicom-mcp /path/to/configuration.yaml

开发

设置开发环境

1. 克隆仓库：

   git clone https://github.com/yourusername/dicom-mcp.git
   cd dicom-mcp
   

2. 创建虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   

3. 安装依赖项：

   pip install -e .
   

运行测试

测试需要一个正在运行的 Orthanc 服务器。你可以使用 Docker 启动一个：

cd tests
docker-compose up -d

然后运行测试：

pytest tests/test_dicom_mcp.py

要测试 PDF 提取功能：

pytest tests/test_dicom_pdf.py

项目结构

• src/dicom_mcp/: 主包
  • __init__.py: 包初始化
  • __main__.py: 入口点
  • server.py: MCP 服务器实现
  • dicom_client.py: DICOM 客户端实现
  • attributes.py: DICOM 属性预设
  • config.py: 使用 Pydantic 的配置管理

许可

该项目根据 MIT 许可协议发布 - 详情请参阅 LICENSE 文件。

致谢

• 基于 pynetdicom
• 遵循 Model Context Protocol 规范
• 使用 PyPDF2 进行 PDF 文本提取