DICOM MCP Server for Medical Imaging Systems 🏥

1# DICOM MCP Server for Medical Imaging Systems 🏥
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
5 [![PyPI Version](https://img.shields.io/pypi/v/dicom-mcp.svg)](https://pypi.org/project/dicom-mcp/) [![PyPI Downloads](https://img.shields.io/pypi/dm/dicom-mcp.svg)](https://pypi.org/project/dicom-mcp/)  
6 
7The `dicom-mcp` server enables AI assistants to query, read, and move data on DICOM servers (PACS, VNA, etc.). 
8 
9<div align="center">
10 
11🤝 **[Contribute](#contributing)** •
12📝 **[Report Bug](https://github.com/ChristianHinge/dicom-mcp/issues)**  •
13📝 **[Blog Post 1](https://www.christianhinge.com/projects/dicom-mcp/)** 
14 
15</div>
16 
17```text
18---------------------------------------------------------------------
19🧑‍⚕️ User: "Any significant findings in John Doe's previous CT report?"
20 
21🧠 LLM → ⚙️ Tools:
22   query_patients → query_studies → query_series → extract_pdf_text_from_dicom
23 
24💬 LLM Response: "The report from 2025-03-26 mentions a history of splenomegaly (enlarged spleen)"
25 
26🧑‍⚕️ User: "What's the volume of his spleen at the last scan and the scan today?"
27 
28🧠 LLM → ⚙️ Tools:
29   (query_studies → query_series → move_series → query_series → extract_pdf_text_from_dicom) x2
30   (The move_series tool sends the latest CT to a DICOM segmentation node, which returns volume PDF report)
31 
32💬 LLM Response: "last year 2024-03-26: 412cm³, today 2025-04-10: 350cm³"
33---------------------------------------------------------------------
34```
35 
36 
37## ✨ Core Capabilities
38 
39`dicom-mcp` provides tools to:
40 
41* **🔍 Query Metadata**: Search for patients, studies, series, and instances using various criteria.
42* **📄 Read DICOM Reports (PDF)**: Retrieve DICOM instances containing encapsulated PDFs (e.g., clinical reports) and extract the text content.
43* **➡️ Send DICOM Images**: Send series or studies to other DICOM destinations, e.g. AI endpoints for image segmentation, classification, etc.
44* **⚙️ Utilities**: Manage connections and understand query options.
45 
46## 🚀 Quick Start
47### 📥 Installation
48Install using uv or pip:
49 
50```bash
51uv tool install dicom-mcp
52```
53Or by cloning the repository:
54 
55```bash
56# Clone and set up development environment
57git clone https://github.com/ChristianHinge/dicom-mcp
58cd dicom mcp
59 
60# Create and activate virtual environment
61uv venv
62source .venv/bin/activate
63 
64# Install with test dependencies
65uv pip install -e ".[dev]"
66```
67 
68 
69### ⚙️ Configuration
70 
71`dicom-mcp` requires a YAML configuration file (`config.yaml` or similar) defining DICOM nodes and calling AE titles. Adapt the configuration or keep as is for compatibility with the sample ORTHANC  Server.
72 
73```yaml
74nodes:
75  main:
76    host: "localhost"
77    port: 4242 
78    ae_title: "ORTHANC"
79    description: "Local Orthanc DICOM server"
80 
81current_node: "main"
82calling_aet: "MCPSCU" 
83```
84> [!WARNING]
85DICOM-MCP is not meant for clinical use, and should not be connected with live hospital databases or databases with patient-sensitive data. Doing so could lead to both loss of patient data, and leakage of patient data onto the internet. DICOM-MCP can be used with locally hosted open-weight LLMs for complete data privacy. 
86 
87### (Optional) Sample ORTHANC server
88If you don't have a DICOM server available, you can run a local ORTHANC server using Docker:
89 
90Clone the repository and install test dependencies `pip install -e ".[dev]`
91 
92```bash
93cd tests
94docker ocmpose up -d
95cd ..
96pytest # uploads dummy pdf data to ORTHANC server
97```
98UI at [http://localhost:8042](http://localhost:8042)
99 
100### 🔌 MCP Integration
101 
102Add to your client configuration (e.g. `claude_desktop_config.json`):
103 
104```json
105{
106  "mcpServers": {
107    "dicom": {
108      "command": "uvx",
109      "args": ["dicom-mcp", "/path/to/your_config.yaml"]
110    }
111  }
112}
113```
114 
115For development:
116 
117```json
118{
119    "mcpServers": {
120        "arxiv-mcp-server": {
121            "command": "uv",
122            "args": [
123                "--directory",
124                "path/to/cloned/dicom-mcp",
125                "run",
126                "dicom-mcp",
127                "/path/to/your_config.yaml"
128            ]
129        }
130    }
131}
132```
133 
134 
135## 🛠️ Tools Overview
136 
137`dicom-mcp` provides four categories of tools for interaction with DICOM servers and DICOM data. 
138 
139### 🔍 Query Metadata
140 
141* **`query_patients`**: Search for patients based on criteria like name, ID, or birth date.
142* **`query_studies`**: Find studies using patient ID, date, modality, description, accession number, or Study UID.
143* **`query_series`**: Locate series within a specific study using modality, series number/description, or Series UID.
144* **`query_instances`**: Find individual instances (images/objects) within a series using instance number or SOP Instance UID
145### 📄 Read DICOM Reports (PDF)
146 
147* **`extract_pdf_text_from_dicom`**: Retrieve a specific DICOM instance containing an encapsulated PDF and extract its text content.
148 
149### ➡️ Send DICOM Images
150 
151* **`move_series`**: Send a specific DICOM series to another configured DICOM node using C-MOVE.
152* **`move_study`**: Send an entire DICOM study to another configured DICOM node using C-MOVE.
153 
154### ⚙️ Utilities
155 
156* **`list_dicom_nodes`**: Show the currently active DICOM node and list all configured nodes.
157* **`switch_dicom_node`**: Change the active DICOM node for subsequent operations.
158* **`verify_connection`**: Test the DICOM network connection to the currently active node using C-ECHO.
159* **`get_attribute_presets`**: List the available levels of detail (minimal, standard, extended) for metadata query results.<p>
160 
161 
162### Example interaction
163The tools can be chained together to answer complex questions:
164 
165 
166<div align="center">
167<img src="images/example.png" alt="My Awesome Diagram" width="700">
168</div>
169 
170 
171## 📈 Contributing
172### Running Tests
173 
174Tests require a running Orthanc DICOM server. You can use Docker:
175 
176```bash
177# Navigate to the directory containing docker-compose.yml (e.g., tests/)
178cd tests
179docker-compose up -d
180```
181 
182Run tests using pytest:
183 
184```bash
185# From the project root directory
186pytest
187```
188 
189Stop the Orthanc container:
190 
191```bash
192cd tests
193docker-compose down
194```
195 
196### Debugging
197 
198Use the MCP Inspector for debugging the server communication:
199 
200```bash
201npx @modelcontextprotocol/inspector uv run dicom-mcp /path/to/your_config.yaml --transport stdio
202```
203 
204## 🙏 Acknowledgments
205 
206* Built using [pynetdicom](https://github.com/pydicom/pynetdicom)
207* Uses [PyPDF2](https://pypi.org/project/PyPDF2/) for PDF text extraction
208