MCP HubMCP Hub
ChristianHinge

dicom-mcp

by: ChristianHinge

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

23created 11/03/2025
Visit
DICOM
protocol

📌Overview

Purpose: To provide a Model Context Protocol server for interactions with DICOM servers, enabling access and analysis of medical imaging metadata by AI assistants.

Overview: dicom-mcp acts as an intermediary that facilitates queries to DICOM servers, allowing for the retrieval of patient information, studies, series, instances, and PDF content from DICOM files. The server is built with pynetdicom and adheres to the Model Context Protocol, streamlining the integration of medical imagery and AI models.

Key Features:

  • Querying DICOM Nodes: Users can list and switch between various configured DICOM nodes and calling AE titles, ensuring seamless connectivity.

  • Patient and Study Queries: Supports detailed search functionalities for patient information and medical studies based on various criteria, including patient names, IDs, study dates, modalities, and more.

  • Instance Retrieval: Provides the ability to retrieve specific DICOM instances and encapsulated PDF documents, facilitating text extraction and further analysis in clinical contexts.

dicom-mcp: A DICOM Model Context Protocol Server

This repository provides a Model Context Protocol server for DICOM (Digital Imaging and Communications in Medicine) interactions. It enables Large Language Models to access and analyze medical imaging metadata by querying and interacting with DICOM servers.

dicom-mcp allows AI assistants to query patient information, studies, series, and instances from DICOM servers using standard DICOM networking protocols. It also supports extracting text from encapsulated PDF documents stored in DICOM format, enabling analysis of clinical reports. The server is built on pynetdicom and follows the Model Context Protocol specification.

Features

Tools

  1. list_dicom_nodes
    Lists all configured DICOM nodes and calling AE titles. Returns the current node, available nodes, current calling AE title, and available calling AE titles.

  2. switch_dicom_node
    Switches to a different configured DICOM node.
    Input: node_name (string)

  3. switch_calling_aet
    Switches to a different calling AE title.
    Input: aet_name (string)

  4. verify_connection
    Tests connectivity to the configured DICOM node using C-ECHO.

  5. query_patients
    Search patients matching specified criteria.
    Inputs: name_pattern, patient_id, birth_date, attribute_preset, additional_attributes, exclude_attributes

  6. query_studies
    Search studies matching specified criteria.
    Inputs: patient_id, study_date, modality_in_study, study_description, accession_number, study_instance_uid, attribute_preset, additional_attributes, exclude_attributes

  7. query_series
    Search series within a study.
    Inputs: study_instance_uid (required), modality, series_number, series_description, series_instance_uid, attribute_preset, additional_attributes, exclude_attributes

  8. query_instances
    Search instances within a series.
    Inputs: series_instance_uid (required), instance_number, sop_instance_uid, attribute_preset, additional_attributes, exclude_attributes

  9. get_attribute_presets
    Lists available attribute presets for queries.

  10. retrieve_instance
    Retrieves a specific DICOM instance and saves it locally.
    Inputs: study_instance_uid, series_instance_uid, sop_instance_uid, output_directory (optional)

  11. extract_pdf_text_from_dicom
    Retrieves a DICOM instance containing an encapsulated PDF and extracts its text content.
    Inputs: study_instance_uid, series_instance_uid, sop_instance_uid

Installation

Prerequisites

  • Python 3.12 or higher
  • A DICOM server (e.g., Orthanc, dcm4chee)

Installation via pip

pip install dicom-mcp

Configuration

Create a YAML configuration file defining DICOM nodes and calling AE titles. Example structure:

nodes:
  orthanc:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server"
  
  clinical:
    host: "pacs.hospital.org"
    port: 11112
    ae_title: "CLIN_PACS"
    description: "Clinical PACS server"

calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE title"
  
  modality:
    ae_title: "MODALITY"
    description: "Simulating a modality"

current_node: "orthanc"
current_calling_aet: "default"

Usage

Command Line

Run the server with:

dicom-mcp /path/to/configuration.yaml

Or using uv:

uv run dicom-mcp /path/to/configuration.yaml

Integration Examples

  • Claude Desktop: Add to claude_desktop_config.json under mcpServers.
  • Zed Editor: Add appropriate settings in settings.json for context_servers.

Example Queries

# List nodes
list_dicom_nodes()

# Switch node
switch_dicom_node(node_name="clinical")

# Switch calling AE title
switch_calling_aet(aet_name="modality")

# Verify connection
verify_connection()

# Query patients by name or ID
patients = query_patients(name_pattern="SMITH*")
patients = query_patients(patient_id="12345678", attribute_preset="extended")

# Query studies
studies = query_studies(patient_id="12345678")
studies = query_studies(study_date="20230101-20231231")
studies = query_studies(modality_in_study="CT")

# Query series in study
series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1")
series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1", modality="CT", series_description="CHEST*")

# Query instances in series
instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2")
instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2", instance_number="1")

# Retrieve DICOM instance
result = retrieve_instance(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.3",
    output_directory="./dicom_files"
)

# Extract text from encapsulated PDF in DICOM
result = extract_pdf_text_from_dicom(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.3"
)

Debugging

Use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector uv --directory /path/to/dicom-mcp run dicom-mcp /path/to/configuration.yaml

Development

Setup

  1. Clone the repo:
git clone https://github.com/yourusername/dicom-mcp.git
cd dicom-mcp
  1. Create a virtual environment and activate:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install dependencies in editable mode:
pip install -e .

Running Tests

Requires a running Orthanc server. Start with Docker:

cd tests
docker-compose up -d

Run tests with:

pytest tests/test_dicom_mcp.py
pytest tests/test_dicom_pdf.py  # For PDF extraction tests

Project Structure

  • src/dicom_mcp/: Main package
    • __init__.py: Package initialization
    • __main__.py: Entry point
    • server.py: MCP server implementation
    • dicom_client.py: DICOM client implementation
    • attributes.py: DICOM attribute presets
    • config.py: Configuration management with Pydantic

License

This project is licensed under the MIT License.

Acknowledgments

  • Built on pynetdicom
  • Follows the Model Context Protocol specification
  • Uses PyPDF2 for PDF text extraction