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.

$3

- 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

$3

- Python 3.9+
- Playwright (for browser automation)

$3

``bash


Install the package in development mode

pip install -e .

Install Playwright browsers (required once)

playwright install chromium
`

Usage

$3

`bash


Start the MCP server (stdio transport)

dicom-mcp

Or with explicit Python

python -m dicom_mcp.server
`

$3

#### Method 1: Local Python Deployment

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

`json
{
"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.

`json
{
"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

$3

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

$3

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

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

$3

Get information about all supported providers.

Returns: List of provider information with supported domains and descriptions

$3

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

$3

`python


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
)
`

$3

`python


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
)
`

$3

`python


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

$3

`bash


Run with pytest (after installing dev dependencies)


pip install -e ".[dev]"
pytest tests/
`

$3

`bash


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