Skip to content
Back to search

dicom-mcp

Model Context Protocol (MCP) for interacting with dicom servers (PACS etc.)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/christianhinge--dicom-mcp/badge.svg)](/listings/christianhinge--dicom-mcp)

HTML

<a href="/listings/christianhinge--dicom-mcp"><img src="/api/listings/christianhinge--dicom-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

πŸ“₯ Installation

Install using uv or pip:

uv tool install dicom-mcp

Or by cloning the repository:

# Clone and set up development environment
git clone https://github.com/ChristianHinge/dicom-mcp
cd dicom mcp

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install with test dependencies
uv pip install -e ".[dev]"

βš™οΈ Configuration

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

nodes:
  main:
    host: "localhost"
    port: 4242 
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server"

current_node: "main"
calling_aet: "MCPSCU" 

> [!WARNING] DICOM-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.

(Optional) Sample ORTHANC server

If you don't have a DICOM server available, you can run a local ORTHANC server using Docker:

Clone the repository and install test dependencies `pip install -e ".[dev]`

cd tests
docker compose up -d
cd ..
pytest # uploads dummy pdf data to ORTHANC server

UI at [http://localhost:8042](http://localhost:8042)

πŸ”Œ MCP Integration

Add to your client configuration (e.g. `claude_desktop_config.json`):

{
  "mcpServers": {
    "dicom": {
      "command": "uvx",
      "args": ["dicom-mcp", "/path/to/your_config.yaml"]
    }
  }
}

For development:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "path/to/cloned/dicom-mcp",
                "run",
                "dicom-mcp",
                "/path/to/your_config.yaml"
            ]
        }
    }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DICOM MCP Server for Medical Imaging Systems πŸ₯
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  4. [![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/)
  5. The `dicom-mcp` server enables AI assistants to query, read, and move data on DICOM servers (PACS, VNA, etc.).
  6. <div align="center">
  7. 🀝 **[Contribute](#contributing)** β€’
  8. πŸ“ **[Report Bug](https://github.com/ChristianHinge/dicom-mcp/issues)** β€’
  9. πŸ“ **[Blog Post 1](https://www.christianhinge.com/projects/dicom-mcp/)**
  10. </div>
  11. ```text
  12. ---------------------------------------------------------------------
  13. πŸ§‘β€βš•οΈ User: "Any significant findings in John Doe's previous CT report?"
  14. 🧠 LLM β†’ βš™οΈ Tools:
  15. query_patients β†’ query_studies β†’ query_series β†’ extract_pdf_text_from_dicom
  16. πŸ’¬ LLM Response: "The report from 2025-03-26 mentions a history of splenomegaly (enlarged spleen)"
  17. πŸ§‘β€βš•οΈ User: "What's the volume of his spleen at the last scan and the scan today?"
  18. 🧠 LLM β†’ βš™οΈ Tools:
  19. (query_studies β†’ query_series β†’ move_series β†’ query_series β†’ extract_pdf_text_from_dicom) x2
  20. (The move_series tool sends the latest CT to a DICOM segmentation node, which returns volume PDF report)
  21. πŸ’¬ LLM Response: "last year 2024-03-26: 412cmΒ³, today 2025-04-10: 350cmΒ³"
  22. ---------------------------------------------------------------------
  23. ```
  24. ## ✨ Core Capabilities
  25. `dicom-mcp` provides tools to:
  26. * **πŸ” Query Metadata**: Search for patients, studies, series, and instances using various criteria.
  27. * **πŸ“„ Read DICOM Reports (PDF)**: Retrieve DICOM instances containing encapsulated PDFs (e.g., clinical reports) and extract the text content.
  28. * **➑️ Send DICOM Images**: Send series or studies to other DICOM destinations, e.g. AI endpoints for image segmentation, classification, etc.
  29. * **βš™οΈ Utilities**: Manage connections and understand query options.
  30. ## πŸš€ Quick Start
  31. ### πŸ“₯ Installation
  32. Install using uv or pip:
  33. ```bash
  34. uv tool install dicom-mcp
  35. ```
  36. Or by cloning the repository:
  37. ```bash
  38. # Clone and set up development environment
  39. git clone https://github.com/ChristianHinge/dicom-mcp
  40. cd dicom mcp
  41. # Create and activate virtual environment
  42. uv venv
  43. source .venv/bin/activate
  44. # Install with test dependencies
  45. uv pip install -e ".[dev]"
  46. ```
  47. ### βš™οΈ Configuration
  48. `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.
  49. ```yaml
  50. nodes:
  51. main:
  52. host: "localhost"
  53. port: 4242
  54. ae_title: "ORTHANC"
  55. description: "Local Orthanc DICOM server"
  56. current_node: "main"
  57. calling_aet: "MCPSCU"
  58. ```
  59. > [!WARNING]
  60. DICOM-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.
  61. ### (Optional) Sample ORTHANC server
  62. If you don't have a DICOM server available, you can run a local ORTHANC server using Docker:
  63. Clone the repository and install test dependencies `pip install -e ".[dev]`
  64. ```bash
  65. cd tests
  66. docker compose up -d
  67. cd ..
  68. pytest # uploads dummy pdf data to ORTHANC server
  69. ```
  70. UI at [http://localhost:8042](http://localhost:8042)
  71. ### πŸ”Œ MCP Integration
  72. Add to your client configuration (e.g. `claude_desktop_config.json`):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "dicom": {
  77. "command": "uvx",
  78. "args": ["dicom-mcp", "/path/to/your_config.yaml"]
  79. }
  80. }
  81. }
  82. ```
  83. For development:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "arxiv-mcp-server": {
  88. "command": "uv",
  89. "args": [
  90. "--directory",
  91. "path/to/cloned/dicom-mcp",
  92. "run",
  93. "dicom-mcp",
  94. "/path/to/your_config.yaml"
  95. ]
  96. }
  97. }
  98. }
  99. ```
  100. #### Running over HTTP
  101. By default the server speaks stdio and is launched by the MCP client. To run it as a standalone server instead, use the streamable-HTTP transport:
  102. ```bash
  103. uv run dicom-mcp /path/to/your_config.yaml --transport http --host 127.0.0.1 --port 8000
  104. ```
  105. Clients then connect to `http://127.0.0.1:8000/mcp`; Claude Desktop does so through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
  106. ```json
  107. {
  108. "mcpServers": {
  109. "dicom": {
  110. "command": "npx",
  111. "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
  112. }
  113. }
  114. }
  115. ```
  116. The HTTP transport runs stateless, so the server can be restarted while the client keeps running. `--transport sse` (the legacy SSE transport) accepts the same `--host`/`--port` options.
  117. The HTTP and SSE endpoints have **no authentication**. Bound to `127.0.0.1` (the default), they reject requests whose `Host` or `Origin` header names another site, which keeps web pages in your browser from reaching them through DNS rebinding. Binding to any other address exposes the server to every host that can reach it; keep it behind a firewall or an authenticating reverse proxy.
  118. ## πŸ› οΈ Tools Overview
  119. `dicom-mcp` provides four categories of tools for interaction with DICOM servers and DICOM data.
  120. ### πŸ” Query Metadata
  121. * **`query_patients`**: Search for patients based on criteria like name, ID, or birth date.
  122. * **`query_studies`**: Find studies using patient ID, date, modality, description, accession number, or Study UID.
  123. * **`query_series`**: Locate series within a specific study using modality, series number/description, or Series UID.
  124. * **`query_instances`**: Find individual instances (images/objects) within a series using instance number or SOP Instance UID
  125. ### πŸ“„ Read DICOM Reports (PDF)
  126. * **`extract_pdf_text_from_dicom`**: Retrieve a specific DICOM instance containing an encapsulated PDF and extract its text content.
  127. ### ➑️ Send DICOM Images
  128. * **`move_series`**: Send a specific DICOM series to another configured DICOM node using C-MOVE.
  129. * **`move_study`**: Send an entire DICOM study to another configured DICOM node using C-MOVE.
  130. ### βš™οΈ Utilities
  131. * **`list_dicom_nodes`**: Show the currently active DICOM node and list all configured nodes.
  132. * **`switch_dicom_node`**: Change the active DICOM node for subsequent operations.
  133. * **`verify_connection`**: Test the DICOM network connection to the currently active node using C-ECHO.
  134. * **`get_attribute_presets`**: List the available levels of detail (minimal, standard, extended) for metadata query results.<p>
  135. ### Example interaction
  136. The tools can be chained together to answer complex questions:
  137. <div align="center">
  138. <img src="images/example.png" alt="My Awesome Diagram" width="700">
  139. </div>
  140. ## πŸ“ˆ Contributing
  141. ### Running Tests
  142. Tests require a running Orthanc DICOM server. You can use Docker:
  143. ```bash
  144. # Navigate to the directory containing docker-compose.yml (e.g., tests/)
  145. cd tests
  146. docker-compose up -d
  147. ```
  148. Run tests using pytest:
  149. ```bash
  150. # From the project root directory
  151. pytest
  152. ```
  153. Stop the Orthanc container:
  154. ```bash
  155. cd tests
  156. docker-compose down
  157. ```
  158. ### Debugging
  159. Use the MCP Inspector for debugging the server communication:
  160. ```bash
  161. npx @modelcontextprotocol/inspector uv run dicom-mcp /path/to/your_config.yaml --transport stdio
  162. ```
  163. ## πŸ™ Acknowledgments
  164. * Built using [pynetdicom](https://github.com/pydicom/pynetdicom)
  165. * Uses [PyPDF2](https://pypi.org/project/PyPDF2/) for PDF text extraction

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.