Docker Medical Imaging MCP Server

A Model Context Protocol (MCP) server for Docker-based medical image processing, enabling Claude Desktop to orchestrate medical imaging workflows including DICOM, NIfTI conversion, and AI segmentation with TotalSegmentator.

Features

• DICOM Management: Pull/push series from Orthanc PACS
• Unified Pipeline: Single container handles DICOM → NIfTI → TotalSegmentator → DICOM-SEG
• Statistics Output: Volume/intensity statistics for every segmentation
• Orthanc Integration: Optional upload of generated DICOM-SEG objects
• Conversational PACS Querying: Browse patients, studies, and series directly from chat

Prerequisites

1. Docker Desktop - Running and accessible
2. Node.js - Version 18 or higher
3. Claude Desktop - Installed on your Mac
4. Docker Images

   cd full-pipeline && ./build.sh
   cd ../orthanc-tools && docker build -t medical-imaging-orthanc-tools:latest .

Installation

Step 1: Install Dependencies

cd /Users/jonas/Projekte/docker-medical-imaging-tutorial/docker-mcp-medical
npm install

Step 2: Configure Claude Desktop

Claude Desktop looks for MCP server configurations in:

~/Library/Application Support/Claude/claude_desktop_config.json

Edit this file to add your MCP server:

{
  "mcpServers": {
    "docker-medical-imaging": {
      "command": "node",
      "args": [
        "/Users/jonas/Projekte/docker-medical-imaging-tutorial/docker-mcp-medical/index.js"
      ],
      "env": {
        "ORTHANC_URL": "http://host.docker.internal:3001/orthanc",
        "ORTHANC_USERNAME": "",
        "ORTHANC_PASSWORD": ""
      }
    }
  }
}

Important: Use the absolute path to your index.js file!

Step 3: Restart Claude Desktop

1. Quit Claude Desktop completely (⌘+Q)
2. Relaunch Claude Desktop
3. Look for the 🔌 icon in the bottom-right corner - it should show your MCP server is connected

Environment Variables

Configure these in the claude_desktop_config.json:

• ORTHANC_URL: URL to your Orthanc PACS server (default: http://host.docker.internal:3001/orthanc)
• ORTHANC_USERNAME: Orthanc username (if authentication enabled)
• ORTHANC_PASSWORD: Orthanc password (if authentication enabled)

Available Tools

1. list_pacs_patients

Query Orthanc for patients (filter by name/ID, limit results).

2. list_pacs_studies

List studies for a patient or the archive (filter by patient/modality).

3. list_pacs_series

Enumerate series within a study, optionally filtering by modality.

4. find_pacs_series

Search series across the PACS by modality, body part, or patient name.

5. describe_series_coverage

Summarize slice count and bounding-box coverage for a series.

6. generate_series_preview

Generate a PNG preview for quick visual inspection; the image is attached to the chat.

7. list_pipeline_results

Inspect cached processing results (NIfTI, segmentation outputs, previews) for a series.

8. check_pipeline_segmentation

Verify whether specific organs are available for a series/run combination. Pass attach_files: true to receive the matching NIfTI masks directly in the chat.

9. clear_pipeline_results

Remove cached outputs for a series (optionally delete the downloaded DICOM set).

10. pull_series_from_orthanc

Download a series into the shared volume for local processing.

11. push_to_orthanc

Upload local DICOM files (single file or directory) back to Orthanc.

12. list_files

Inspect the shared Docker volume.

13. run_full_pipeline

Run the complete workflow (pull → NIfTI → TotalSegmentator → DICOM-SEG → optional upload). Results are stored under /data/<SeriesInstanceUID>/.... Supports a retry flag to force regeneration and attaches the resulting NIfTI, DICOM-SEG, and statistics JSON directly in the chat.

Example Usage in Claude Desktop

Once configured, you can ask Claude:

"Run the medical imaging pipeline on series abc123 and upload the results back to Orthanc"

"Process series xyz789 with fast mode and only keep the liver, spleen, and kidneys"

"Execute the pipeline for series 456def with task=cerebral_bleed, generate statistics, and skip uploading the SEG"

Claude will use the MCP tools to execute these workflows automatically!

Output Layout

All artifacts are written under /data/<SeriesInstanceUID>/ with per-run subfolders:

• dicom/ – downloaded instances (shared across runs).
• nifti/<run_label>.nii.gz – converted volumes.
• segmentations/<run_label>/ – TotalSegmentator masks.
• outputs/<run_label>/ – multilabel NIfTI, DICOM-SEG, statistics, summary.json.
• previews/ – thumbnails produced by generate_series_preview.

The new management tools can list, validate, or clear these folders directly from the chat.

Testing Without Claude Desktop

Use the included test client to verify your MCP server works:

# List all available tools
node test-mcp.js list

# Test a simple tool
node test-mcp.js call list_files '{"path":"."}'

# Run the full pipeline (adjust series_id before testing)
node test-mcp.js call run_full_pipeline '{
  "series_id": "SERIES_ID",
  "workflow_name": "test_run",
  "fast": true,
  "keep_segments": ["liver","spleen"],
  "statistics": true,
  "upload_results": false
}'

See test-examples.sh for more examples.

Apple Silicon GPU Support

Important: Apple Silicon GPU acceleration (MPS - Metal Performance Shaders) is NOT available inside Docker containers, even on arm64/Apple Silicon Macs.

This is because:

• Docker containers run Linux
• MPS is a macOS-specific framework
• Linux does not support the MPS device

To use Apple GPU acceleration:

1. Install TotalSegmentator natively on macOS (outside Docker)
2. Run: pip install TotalSegmentator
3. Use: TotalSegmentator -i input.nii -o output/ -d mps

Inside Docker (including this MCP server):

• Use device: "cpu" (default) - works on all platforms
• Use device: "gpu" - requires NVIDIA GPU + CUDA (Linux/Windows only)
• MPS is not supported

Troubleshooting

MCP Server Not Showing in Claude Desktop

1. Check the config file path: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Verify the absolute path to index.js is correct
3. Make sure node_modules are installed: npm install
4. Restart Claude Desktop completely (⌘+Q, then relaunch)
5. Check Claude Desktop logs: ~/Library/Logs/Claude/

Docker Images Not Found

Make sure you've built the unified pipeline image:

cd full-pipeline && ./build.sh

Verify images exist:

docker images | grep medical-imaging

TotalSegmentator Running Slow

• Use fast: true for 3mm resolution (faster)
• Use fastest: true for 6mm resolution (much faster)
• Use roi_subset: ["organ1", "organ2"] to segment only specific organs
• On CPU, segmentation can take 5-30 minutes depending on image size and settings

Architecture

Claude Desktop (LLM)
    ↓ MCP Protocol
MCP Server (Node.js)
    ↓ Docker API
medical-imaging-pipeline container
    ├─ Orthanc download (requests)
    ├─ dcm2niix conversion
    ├─ TotalSegmentator processing
    ├─ DICOM-SEG creation (highdicom)
    └─ Statistics JSON output

License

MIT

References

• MCP Documentation
• TotalSegmentator
• dcm2niix
• Orthanc PACS