Dicom

dicom-mcp: A DICOM Model Context Protocol Server

This repo is part of a blog post: Agentic Healthcare LLMs

Overview

A Model Context Protocol server for DICOM (Digital Imaging and Communications in Medicine) interactions. This server provides tools to query and interact with DICOM servers, enabling Large Language Models to access and analyze medical imaging metadata.

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, making it possible to analyze clinical reports. It's built on pynetdicom and follows the Model Context Protocol specification.

Tools

list_dicom_nodes
- Lists all configured DICOM nodes and calling AE titles
- Inputs: None
- Returns: Current node, available nodes, current calling AE title, and available calling AE titles
switch_dicom_node
- Switches to a different configured DICOM node
- Inputs:
  - node_name (string): Name of the node to switch to
- Returns: Success message
switch_calling_aet
- Switches to a different configured calling AE title
- Inputs:
  - aet_name (string): Name of the calling AE title to switch to
- Returns: Success message
verify_connection
- Tests connectivity to the configured DICOM node using C-ECHO
- Inputs: None
- Returns: Success or failure message with details
query_patients
- Search for patients matching specified criteria
- Inputs:
  - name_pattern (string, optional): Patient name pattern (can include wildcards)
  - patient_id (string, optional): Patient ID
  - birth_date (string, optional): Patient birth date (YYYYMMDD)
  - attribute_preset (string, optional): Preset level of detail (minimal, standard, extended)
  - additional_attributes (string[], optional): Additional DICOM attributes to include
  - exclude_attributes (string[], optional): DICOM attributes to exclude
- Returns: Array of matching patient records
query_studies
- Search for studies matching specified criteria
- Inputs:
  - patient_id (string, optional): Patient ID
  - study_date (string, optional): Study date or range (YYYYMMDD or YYYYMMDD-YYYYMMDD)
  - modality_in_study (string, optional): Modalities in study
  - study_description (string, optional): Study description (can include wildcards)
  - accession_number (string, optional): Accession number
  - study_instance_uid (string, optional): Study Instance UID
  - attribute_preset (string, optional): Preset level of detail
  - additional_attributes (string[], optional): Additional DICOM attributes to include
  - exclude_attributes (string[], optional): DICOM attributes to exclude
- Returns: Array of matching study records
query_series
- Search for series within a study
- Inputs:
  - study_instance_uid (string): Study Instance UID (required)
  - modality (string, optional): Modality (e.g., "CT", "MR")
  - series_number (string, optional): Series number
  - series_description (string, optional): Series description
  - series_instance_uid (string, optional): Series Instance UID
  - attribute_preset (string, optional): Preset level of detail
  - additional_attributes (string[], optional): Additional DICOM attributes to include
  - exclude_attributes (string[], optional): DICOM attributes to exclude
- Returns: Array of matching series records
query_instances
- Search for instances within a series
- Inputs:
  - series_instance_uid (string): Series Instance UID (required)
  - instance_number (string, optional): Instance number
  - sop_instance_uid (string, optional): SOP Instance UID
  - attribute_preset (string, optional): Preset level of detail
  - additional_attributes (string[], optional): Additional DICOM attributes to include
  - exclude_attributes (string[], optional): DICOM attributes to exclude
- Returns: Array of matching instance records
get_attribute_presets
- Lists available attribute presets for queries
- Inputs: None
- Returns: Dictionary of available presets and their attributes by level
retrieve_instance
- Retrieves a specific DICOM instance and saves it to the local filesystem
- Inputs:
  - study_instance_uid (string): Study Instance UID
  - series_instance_uid (string): Series Instance UID
  - sop_instance_uid (string): SOP Instance UID
  - output_directory (string, optional): Directory to save the retrieved instance to (default: "./retrieved_files")
- Returns: Dictionary with information about the retrieval operation
extract_pdf_text_from_dicom
- Retrieves a DICOM instance containing an encapsulated PDF and extracts its text content
- Inputs:
  - study_instance_uid (string): Study Instance UID
  - series_instance_uid (string): Series Instance UID
  - sop_instance_uid (string): SOP Instance UID
- Returns: Dictionary with extracted text information and status

Installation

Prerequisites

Python 3.12 or higher
A DICOM server to connect to (e.g., Orthanc, dcm4chee, etc.)

Using pip

Install via pip:

1pip install dicom-mcp

Configuration

dicom-mcp requires a YAML configuration file that defines the DICOM nodes and calling AE titles. Create a configuration file with the following structure:

1# DICOM nodes configuration
2nodes:
3  orthanc:
4    host: "localhost"
5    port: 4242
6    ae_title: "ORTHANC"
7    description: "Local Orthanc DICOM server"
8  
9  clinical:
10    host: "pacs.hospital.org"
11    port: 11112
12    ae_title: "CLIN_PACS"
13    description: "Clinical PACS server"
14
15# Local calling AE titles
16calling_aets:
17  default:
18    ae_title: "MCPSCU"
19    description: "Default calling AE title"
20  
21  modality:
22    ae_title: "MODALITY"
23    description: "Simulating a modality"
24
25# Currently selected node
26current_node: "orthanc"
27
28# Currently selected calling AE title
29current_calling_aet: "default"

Usage

Command Line

Run the server using the script entry point:

1dicom-mcp /path/to/configuration.yaml

If using uv:

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

Configuration with Claude Desktop

Add this to your claude_desktop_config.json:

1"mcpServers": {
2  "dicom": {
3    "command": "uv",
4    "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
5  }
6}

Usage with Zed

Add to your Zed settings.json:

1"context_servers": [
2  "dicom-mcp": {
3    "command": {
4      "path": "uv",
5      "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
6    }
7  }
8],

Example Queries

List available DICOM nodes

1list_dicom_nodes()

Switch to a different node

1switch_dicom_node(node_name="clinical")

Switch to a different calling AE title

1switch_calling_aet(aet_name="modality")

Verify connection

1verify_connection()

Search for patients

1# Search by name pattern (using wildcard)
2patients = query_patients(name_pattern="SMITH*")
3
4# Search by patient ID
5patients = query_patients(patient_id="12345678")
6
7# Get detailed information
8patients = query_patients(patient_id="12345678", attribute_preset="extended")

Search for studies

1# Find all studies for a patient
2studies = query_studies(patient_id="12345678")
3
4# Find studies within a date range
5studies = query_studies(study_date="20230101-20231231")
6
7# Find studies by modality
8studies = query_studies(modality_in_study="CT")

Search for series in a study

1# Find all series in a study
2series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1")
3
4# Find series by modality and description
5series = query_series(
6    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
7    modality="CT",
8    series_description="CHEST*"
9)

Search for instances in a series

1# Find all instances in a series
2instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2")
3
4# Find a specific instance by number
5instances = query_instances(
6    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
7    instance_number="1"
8)

Retrieve a DICOM instance

1# Retrieve a specific instance
2result = retrieve_instance(
3    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
4    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
5    sop_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.3",
6    output_directory="./dicom_files"
7)

Extract text from a DICOM encapsulated PDF

1# Extract text from an encapsulated PDF
2result = extract_pdf_text_from_dicom(
3    study_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.1",
4    series_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.2",
5    sop_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.3"
6)

Debugging

You can use the MCP inspector to debug the server:

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

Development

Setup Development Environment

Clone the repository:

1git clone https://github.com/yourusername/dicom-mcp.git
2cd dicom-mcp

Create a virtual environment:

1python -m venv .venv
2source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
1pip install -e .
```

Running Tests

The tests require a running Orthanc server. You can start one using Docker:

1cd tests
2docker-compose up -d

Then run the tests:

1pytest tests/test_dicom_mcp.py

To test PDF extraction functionality:

1pytest tests/test_dicom_pdf.py

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 - see the LICENSE file for details.

Acknowledgments

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

Contents