DICOM MCP Server

English | 中文

A Model Context Protocol (MCP) server for downloading DICOM medical images from multiple Chinese hospital imaging systems.

Overview

This MCP server wraps the dicom_download project, providing a clean interface for LLMs and AI agents to download DICOM images from supported medical imaging providers.

Supported Providers

• tz (天肿): Tianjin Medical University Cancer Institute - zlyy.tjmucih.cn

• fz (复肿): Fudan University Cancer Hospital - ylyyx.shdc.org.cn

• nyfy (宁夏总医院): Ningxia General Hospital - zhyl.nyfy.com.cn

• cloud: Cloud-based DICOM services (*.medicalimagecloud.com and others)

Related MCP server: DICOMweb MCP Server

Installation

Prerequisites

• Python 3.9+

• Playwright (for browser automation)

Setup

# Install the package in development mode
pip install -e .

# Install Playwright browsers (required once)
playwright install chromium

Usage

As an MCP Server

# Start the MCP server (stdio transport)
dicom-mcp

# Or with explicit Python
python -m dicom_mcp.server

Integration with Claude/LLM

Method 1: Local Python Deployment

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "dicom-downloader": {
      "command": "python",
      "args": ["-m", "dicom_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/dicom_mcp"
      }
    }
  }
}

Method 2: NPX Deployment (Recommended)

Using npx, you can run the MCP server directly without manual setup.

⚠️ IMPORTANT: You MUST modify DICOM_DEFAULT_OUTPUT_DIR to use an absolute path. Do NOT use relative paths like ./dicom_downloads.

{
  "mcpServers": {
    "dicom-downloader": {
      "command": "npx",
      "args": ["-y", "dicom-mcp"],
      "env": {
        "DICOM_DEFAULT_OUTPUT_DIR": "/Users/your-username/Downloads/dicom_downloads",
        "DICOM_DEFAULT_MAX_ROUNDS": "3",
        "DICOM_DEFAULT_STEP_WAIT_MS": "40"
      }
    }
  }
}

Configuration Requirements:

• DICOM_DEFAULT_OUTPUT_DIR [REQUIRED TO MODIFY]: Use absolute path (e.g., /Users/username/Downloads/dicom_downloads)

  • ❌ Do NOT use relative paths like ./dicom_downloads (files will be saved to IDE default directories)

  • ✅ Use full paths: /Users/username/... (macOS/Linux) or C:\\Users\\username\\... (Windows)

This method:

• Automatically handles Python dependency detection

• Installs required packages on first run

• No manual PYTHONPATH configuration needed

• Works across different operating systems

• Supports environment variables for default parameters:

  • DICOM_DEFAULT_OUTPUT_DIR: Directory for downloaded files (MUST BE ABSOLUTE PATH)

  • DICOM_DEFAULT_MAX_ROUNDS: Default scan rounds (default: 3)

  • DICOM_DEFAULT_STEP_WAIT_MS: Default delay between frames in ms (default: 40)

Note: First run may take 2-3 minutes as it installs Python dependencies. Subsequent runs will be faster.

Real-Time Progress Feedback

Downloads now display real-time progress information:

======================================================================
🚀 DICOM 下载开始
======================================================================
📍 下载数量: 2 个URL
📁 输出目录: ./dicom_downloads
⚙️  扫描次数: 3, 帧间延迟: 40ms
⏳ 请稍候，下载中... (可能需要 2-10 分钟)

   >>> 打开检查页面: https://ylyyx.shdc.org.cn/viewer?...
   [1/2] provider=fz
   >>> 已进入 viewer iframe
   
======================================================================
✅ 下载完成！处理结果中...
======================================================================

Expected Download Time (varies by parameters and image size):

• Fast mode (2 rounds, 30ms): 1-5 minutes

• Balanced mode (3 rounds, 40ms): 2-8 minutes [recommended]

• Complete mode (5 rounds, 80ms): 4-15 minutes

• Deep scan (10 rounds, 100ms): 8-30 minutes

For details, see PROGRESS_FEEDBACK.md

Available Tools

1. download_dicom

Download DICOM images from a single URL.

Parameters:

• url (required): Medical imaging viewer URL

  • Auto-detects security code: Include code in URL like URL 安全码:8492 and it will be automatically extracted

  • Supports formats: 安全码:8492, 密码:8492, password:8492, code:8492, 验证码:8492

• output_dir (default: ./dicom_downloads): Directory to save downloaded DICOM files

• provider (default: auto): Provider type (auto, tz, fz, nyfy, cloud)

• mode (default: all): Download mode (all, diag, nondiag)

• headless (default: true): Run browser in headless mode (no UI)

• password (optional): Share password/code if required (auto-extracted from URL if present)

• create_zip (default: true): Create ZIP archive of downloaded files

• max_rounds (default: 3): Maximum number of scan rounds (扫描次数) - controls frame-by-frame playback iterations

• step_wait_ms (default: 40): Delay between steps in milliseconds (延迟时间) - delay between frames during playback

Returns:

• success: Whether download succeeded

• output_dir: Directory containing downloaded files

• zip_path: Path to ZIP archive if created

• file_count: Number of files downloaded

• message: Status or error message

2. batch_download_dicom

Download from multiple URLs in batch.

Parameters:

• urls (required): List of URLs to download from

  • Auto-detects security code: Include code in URL like URL 安全码:8492 and it will be automatically extracted

  • Supports formats: 安全码:8492, 密码:8492, password:8492, code:8492, 验证码:8492

• output_parent (default: ./dicom_downloads): Parent directory for all downloads (each URL gets its own subdirectory)

• provider (default: auto): Provider type (auto, tz, fz, nyfy, cloud)

• mode (default: all): Download mode (all, diag, nondiag)

• headless (default: true): Run in headless mode (no UI)

• password (optional): Share password/code if required (auto-extracted from URLs if present)

• create_zip (default: true): Create ZIP archives for each URL

• max_rounds (default: 3): Maximum number of scan rounds (扫描次数) - applied to all URLs

• step_wait_ms (default: 40): Delay between steps in milliseconds (延迟时间) - applied to all URLs

Returns: List of download results for each URL, with success status and file count

3. detect_provider_from_url

Identify which provider a URL belongs to.

Parameters:

• url (required): URL to check

Returns:

• detected_provider: The provider identifier

• provider_info: Details about the provider

• is_auto_detected: Whether detection was successful

4. list_supported_providers

Get information about all supported providers.

Returns: List of provider information with supported domains and descriptions

5. validate_url

Check if a URL is from a supported provider.

Parameters:

• url (required): URL to validate

Returns:

• valid: Whether URL is from a supported provider

• provider: Detected provider if valid

• error: Error message if invalid

Examples

Single Download

# Download from a single URL
download_dicom(
    url="https://zlyy.tjmucih.cn/viewer?share_id=AAAA",
    output_dir="./my_downloads",
    mode="all",
    create_zip=True
)

Batch Download

# Download from multiple URLs
batch_download_dicom(
    urls=[
        "https://zlyy.tjmucih.cn/viewer?share_id=AAAA",
        "https://ylyyx.shdc.org.cn/viewer?share_id=BBBB",
        "https://zhyl.nyfy.com.cn/viewer?share_id=CCCC"
    ],
    output_parent="./batch_downloads",
    provider="auto",  # Auto-detect for each URL
    create_zip=True
)

With Password

# Download URL that requires a password/share code
download_dicom(
    url="https://example.medicalimagecloud.com/viewer?id=XYZ",
    password="secret123",
    provider="cloud"
)

Architecture

dicom_mcp/
├── pyproject.toml          # Project configuration
├── README.md               # This file
└── dicom_mcp/
    ├── __init__.py         # Package initialization
    └── server.py           # MCP server implementation

The MCP server acts as a wrapper around the underlying dicom_download project, handling:

1. Tool Registration: Exposing download functions as MCP tools

2. Input Validation: Validating URLs and parameters

3. Provider Detection: Auto-detecting the correct provider for a URL

4. Process Management: Running the underlying download scripts

5. Result Formatting: Returning structured results to the LLM

Error Handling

The server provides detailed error messages for common issues:

• Invalid URL format

• Unsupported provider domain

• Download failures (expired links, authentication required, etc.)

• File system errors

Security Considerations

• Passwords are passed to the underlying service but not logged or cached

• URLs are validated before processing

• File operations use temporary directories for intermediate results

• The server runs in read-only mode by default (use only for downloads)

Limitations

• Browser Automation: Some providers require Chromium/Firefox via Playwright

• Desktop Environment: Headless mode requires X11 or similar on Linux servers

• Authentication: Some URLs require valid share codes or authentication

• Link Expiration: Share links may expire after a certain period

Development

Running Tests

# Run with pytest (after installing dev dependencies)
pip install -e ".[dev]"
pytest tests/

Building

# Build the package
python -m build

# Or with setuptools directly
python setup.py sdist bdist_wheel

License

This MCP server wrapper is provided under the same license as the underlying dicom_download project (Apache 2.0). See the original project for details.

Credits

• Original project: dicom_download

• Cloud provider adapter based on: cloud-dicom-downloader

Support

For issues with:

• MCP Server: Check this repository

• DICOM Downloads: See the dicom_download project

• Specific Providers: Refer to provider-specific documentation