dicom-tools-mcp 0.3.0

基于 MCP (Model Context Protocol) 的 DICOM 医学影像文件分析工具

DICOM 工具 MCP 服务器

基于 MCP (Model Context Protocol) 的 DICOM 医学影像文件分析工具的 Python 实现。

功能特性

• 🔍 DICOM 目录扫描：快速扫描目录下的所有 DICOM 文件，提供统计摘要
• 📊 序列映射：生成患者-序列的详细映射关系
• 📝 文件解析：解析单个 DICOM 文件，提取完整元数据
• 📤 数据导出：支持 JSON 格式导出 DICOM 元数据
• 🏥 批量分析：智能分析 DICOM 目录并上传到 Orthanc 服务器

项目结构

.
├── main.py                 # MCP 服务器主文件
├── process.py              # DICOM 目录批量分析处理
├── config.json             # 配置文件（服务器地址、认证等）
├── requirements.txt        # Python 依赖包列表
├── dicom_tools/           # DICOM 工具模块
│   ├── scanner.py         # 目录扫描工具
│   ├── parser.py          # DICOM 文件解析器
│   ├── mapping.py         # 序列映射工具
│   ├── exporter.py        # JSON 导出工具
│   ├── types.py           # 类型定义
│   └── utils.py           # 工具函数
└── src/                   # 核心业务逻辑
    ├── api/               # API 接口层
    │   ├── dicom_api.py   # DICOM 文件上传 API
    │   ├── metadata_api.py # 元数据上传 API
    │   └── query_api.py   # 查询 API
    ├── core/              # 核心处理逻辑
    │   ├── series_processor.py # 序列处理器
    │   └── uploader.py    # 上传器
    ├── models/            # 数据模型
    │   └── dicom_models.py # DICOM 数据模型
    └── utils/             # 工具函数
        ├── config_loader.py # 配置加载器
        └── progress.py    # 进度条工具

安装

环境要求

• Python 3.8 或更高版本
• pip 包管理器

安装依赖

uv sync

配置

本工具支持两种配置方式，详细说明请查看 配置指南。

方式一:环境变量(推荐用于 MCP)

在 MCP 配置文件中设置环境变量:

{
  "mcpServers": {
    "dicom-tools": {
      "command": "uvx",
      "args": ["dicom-tools-mcp"],
      "env": {
        "ORTHANC_BASE_URL": "http://your-server:8042",
        "ORTHANC_COOKIE": "your-cookie-value"
      }
    }
  }
}

方式二:配置文件(推荐用于开发)

创建 config.json 文件:

{
  "orthanc_base_url": "http://your-orthanc:8042",
  "cookie": "your-authentication-cookie",
  "max_workers": 4,
  "max_retries": 3,
  "DEFAULT_CONNECT_TIMEOUT": 10,
  "DEFAULT_READ_TIMEOUT": 300,
  "DEFAULT_RETRY_DELAY": 2,
  "DEFAULT_BATCH_SIZE": 10
}

配置优先级: 环境变量 > 配置文件

使用方法

作为 MCP 服务器运行

跟更新config.json文件后运行

uv run main.py --base-url "http://192.168.4.17:29999" --orthanc-url "http://192.168.4.17:18997" --cookie "LoMSnZMGUXfQETiBHu-gUVeHlWBiSOifDVNYwcjqCwqiBSk2nnVAJuf4LM6Q48uj"

在vscodecline运行

{
  "mcpServers": {
    "dicom-tools-python": {
      "autoApprove": [
        "scan-dicom-directory",
        "get-dicom-series-mapping",
        "get-dicom-file-mapping",
        "export-dicom-json",
        "parse-dicom-file"
      ],
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "main.py",
        "--base-url",
        "http://192.168.4.220:26666",
        "--orthanc-url",
        "http://192.168.4.220:18997",
        "--cookie",
        "ls=6ebM3MNdxq1kH0SnFa14UqkS9aEaYuIh6nPW2POoLCsuFDFm_s6qyCvDuexEI0K3"
      ],
      "cwd": "C:/Users/13167/Desktop/agent-mcp/src"
    }
  }
}

服务器将通过标准输入/输出 (stdio) 与 MCP 客户端通信。

可用的工具

1. scan-dicom-directory

扫描指定目录下的所有 DICOM 文件，返回统计摘要。

参数：

• directory_path (string): 要扫描的目录路径

示例：

{
  "directory_path": "/path/to/dicom/folder"
}

2. get-dicom-series-mapping

生成患者-序列的详细映射关系，包含每个序列的文件列表。

参数：

• directory_path (string): 要扫描的目录路径

3. get-dicom-file-mapping

生成优化的文件路径映射。

参数：

• directory_path (string): 要扫描的目录路径

4. parse-dicom-file

解析单个 DICOM 文件，提取完整元数据。

参数：

• file_path (string): DICOM 文件路径

5. export-dicom-json

将 DICOM 文件导出为 JSON 格式。

参数：

• file_path (string): DICOM 文件路径

6. analysis-dicom-directory

批量分析 DICOM 目录并上传到服务器。

参数：

• directory_path (string): 要分析的目录路径
• series_type (string): 序列类型筛选（可选）

主要依赖

• mcp: Model Context Protocol 服务器框架
• pydicom: DICOM 文件读取和解析
• requests: HTTP 请求处理
• pydantic: 数据验证和模型定义
• tqdm: 进度条显示

开发

添加新工具

1. 在 dicom_tools/ 目录下创建新的工具模块
2. 在 main.py 中注册新工具
3. 实现工具的处理逻辑

测试

确保您的 DICOM 文件目录结构正确，然后运行服务器进行测试。

注意事项

• 确保有足够的磁盘空间和内存来处理大型 DICOM 数据集
• 配置文件中的 cookie 需要定期更新以保持认证有效
• 建议在处理大量文件时调整 max_workers 参数以优化性能

许可证

本项目遵循相应的开源许可证。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请通过 GitHub Issue 联系我们。