MCP server for DICOM image downloading from multiple medical imaging sources
npm install dicom-mcpEnglish | 中文
A Model Context Protocol (MCP) server for downloading DICOM medical images from multiple Chinese hospital imaging systems.
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.
- 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)
- Python 3.9+
- Playwright (for browser automation)
``bashInstall the package in development mode
pip install -e .
Usage
$3
`bash
Start the MCP server (stdio transport)
dicom-mcpOr 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 playbackReturns:
-
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 URLsReturns:
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 checkReturns:
-
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 validateReturns:
-
valid: Whether URL is from a supported provider
- provider: Detected provider if valid
- error: Error message if invalidExamples
$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 buildOr 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.- Original project: dicom_download
- Cloud provider adapter based on: cloud-dicom-downloader
For issues with:
- MCP Server: Check this repository
- DICOM Downloads: See the dicom_download project
- Specific Providers: Refer to provider-specific documentation