Glama
Sign In

DICOM MCP Server

by ChristianHinge
Verified
GitHub
Python
13
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

  • Supports integration with Docker for running Orthanc server in development and testing environments.

  • Uses Pydantic for configuration management, providing type validation and settings management for the DICOM MCP server.

  • Provides test suite integration for validating DICOM MCP functionality.

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

  1. 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
  2. switch_dicom_node
    • Switches to a different configured DICOM node
    • Inputs:
      • node_name (string): Name of the node to switch to
    • Returns: Success message
  3. 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
  4. verify_connection
    • Tests connectivity to the configured DICOM node using C-ECHO
    • Inputs: None
    • Returns: Success or failure message with details
  5. 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
  6. 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
  7. 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
  8. 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
  9. get_attribute_presets
    • Lists available attribute presets for queries
    • Inputs: None
    • Returns: Dictionary of available presets and their attributes by level
  10. 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
  11. 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:

pip 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:

# DICOM nodes configuration 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" # Local calling AE titles calling_aets: default: ae_title: "MCPSCU" description: "Default calling AE title" modality: ae_title: "MODALITY" description: "Simulating a modality" # Currently selected node current_node: "orthanc" # Currently selected calling AE title current_calling_aet: "default"

Usage

Command Line

Run the server using the script entry point:

dicom-mcp /path/to/configuration.yaml

If using uv:

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

Configuration with Claude Desktop

Add this to your claude_desktop_config.json:

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

Usage with Zed

Add to your Zed settings.json:

"context_servers": [ "dicom-mcp": { "command": { "path": "uv", "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"] } } ],

Example Queries

List available DICOM nodes

list_dicom_nodes()

Switch to a different node

switch_dicom_node(node_name="clinical")

Switch to a different calling AE title

switch_calling_aet(aet_name="modality")

Verify connection

verify_connection()

Search for patients

# Search by name pattern (using wildcard) patients = query_patients(name_pattern="SMITH*") # Search by patient ID patients = query_patients(patient_id="12345678") # Get detailed information patients = query_patients(patient_id="12345678", attribute_preset="extended")

Search for studies

# Find all studies for a patient studies = query_studies(patient_id="12345678") # Find studies within a date range studies = query_studies(study_date="20230101-20231231") # Find studies by modality studies = query_studies(modality_in_study="CT")

Search for series in a study

# Find all series in a study series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1") # Find series by modality and description series = query_series( study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1", modality="CT", series_description="CHEST*" )

Search for instances in a series

# Find all instances in a series instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2") # Find a specific instance by number instances = query_instances( series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2", instance_number="1" )

Retrieve a DICOM instance

# Retrieve a specific 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 a DICOM encapsulated PDF

# Extract text from an encapsulated PDF 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

You can 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 Development Environment

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

Running Tests

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

cd tests docker-compose up -d

Then run the tests:

pytest tests/test_dicom_mcp.py

To test PDF extraction functionality:

pytest 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

Enables AI assistants to query and analyze medical imaging metadata from DICOM servers, including patient information, studies, series, and instances, as well as extract text from encapsulated PDF documents.

  1. Overview
    1. Tools
  2. Installation
    1. Prerequisites
    2. Using pip
  3. Configuration
    1. Usage
      1. Command Line
      2. Configuration with Claude Desktop
      3. Usage with Zed
    2. Example Queries
      1. List available DICOM nodes
      2. Switch to a different node
      3. Switch to a different calling AE title
      4. Verify connection
      5. Search for patients
      6. Search for studies
      7. Search for series in a study
      8. Search for instances in a series
      9. Retrieve a DICOM instance
      10. Extract text from a DICOM encapsulated PDF
    3. Debugging
      1. Development
        1. Setup Development Environment
        2. Running Tests
        3. Project Structure
      2. License
        1. Acknowledgments