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)

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