Skip to main content
Glama
simple-dicom-mcp

simple-dicom-mcp

by ThalesMMS

Repo credit: https://github.com/ChristianHinge/dicom-mcp

Run it

  • Minimal config (configuration.yaml):

nodes:
  orthanc:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Default Local Orthanc DICOM server"
    aliases: ["local", "dev-orthanc"]

  radiant:
    host: "localhost"
    port: 11112
    ae_title: "RADIANT"
    description: "Radiant Viewer Dicom Node"
    aliases: ["viewer"]

current_node: "orthanc"

calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE"

calling_aet: "default"
query_root: "study"
allow_remote_hosts: false

network:
  acse_timeout: 10
  dimse_timeout: 30
  network_timeout: 30
  assoc_timeout: 10
  max_pdu: 16384
  retry:
    max_attempts: 2
    backoff_seconds: 1.0
    backoff_multiplier: 2.0
    backoff_max_seconds: 5.0
  • Start server (dev):

uv run --with-editable '.' -m dicom_mcp configuration.yaml
  • If uv caches old code: add --no-cache or --reinstall-package simple-dicom-mcp.

Related MCP server: DICOM MCP Server

Claude Desktop (working JSON)

{
  "mcpServers": {
    "DicomMCP": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "--distribution",
        "Ubuntu",
        "--",
        "bash",
        "-lc",
        "cd '/mnt/c/Users/paulo/Python Projects/simple-dicom-mcp' && uv run --with-editable '.' python -m dicom_mcp '/mnt/c/Users/paulo/Python Projects/simple-dicom-mcp/configuration.yaml'"
      ]
    }
  },
  "globalShortcut": "",
  "preferences": {
    "menuBarEnabled": false
  }
}

WSL tips

  • Enable mirrored networking so localhost works for both Windows and WSL.

  • Use --with-editable '.' so your code changes are seen live.

Tools you can call

  • Connection: list_dicom_nodes, switch_dicom_node, verify_connection

  • Registry: get_manifest

  • Query: query_patients, query_studies, query_series, query_instances, get_attribute_presets

Query tools return structured status metadata:

{
  "success": true,
  "results": [],
  "dicom_statuses": [],
  "warnings": [],
  "error": null
}

Examples

  • Find studies in a date range:

query_studies(study_date="20230101-20231231")
  • Filter studies by patient attributes:

query_studies(patient_id="12345678", patient_sex="O", patient_birth_date="19700101")

Troubleshooting

  • If uv doesn’t reflect code changes, add --no-cache or --reinstall-package simple-dicom-mcp.

  • On WSL/Windows, enable mirrored networking so localhost works across Windows and WSL.

License & credit

License: MIT Python Version PyPI Version PyPI Downloads

The simple-dicom-mcp server enables AI assistants to query and read data on DICOM servers (PACS, VNA, etc.).

🀝 Contributing guide β€’ 🐞 Report bug β€’ πŸ›Ÿ Support β€’ πŸ” Security

✨ Core Capabilities

simple-dicom-mcp provides tools to:

  • πŸ” Query Metadata: Search for patients, studies, series, and instances using various criteria.

  • βš™οΈ Utilities: Manage connections and understand query options.

πŸš€ Quick Start

πŸ“₯ Installation

Install using uv:

uv tool install simple-dicom-mcp

Or by cloning the repository:

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

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

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

βš™οΈ Configuration

simple-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"
    aliases: ["local", "dev-orthanc"]

current_node: "main"

calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE"

calling_aet: "default"
query_root: "study"
allow_remote_hosts: false

network:
  acse_timeout: 10
  dimse_timeout: 30
  network_timeout: 30
  assoc_timeout: 10
  max_pdu: 16384
  retry:
    max_attempts: 2
    backoff_seconds: 1.0
    backoff_multiplier: 2.0
    backoff_max_seconds: 5.0

Notes:

  • calling_aet can be a name, alias, or AE title defined in calling_aets.

  • query_root accepts study or patient.

  • allow_remote_hosts defaults to false and blocks non-loopback DICOM hosts unless you explicitly opt in.

WARNING

Simple 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. If you intentionally need a remote PACS or VNA, setallow_remote_hosts: true only after reviewing the risk and using a private, trusted environment.

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

uv pip install -e ".[dev]"

Start Orthanc and run tests:

cd tests
docker compose up -d
cd ..
uv run pytest -m integration

UI at http://localhost:8042

πŸ”Œ MCP Integration

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

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

For development:

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

πŸ› οΈ Tools Overview

simple-dicom-mcp provides five categories of tools for interaction with DICOM servers and DICOM data.

πŸ” Query Metadata

  • query_patients: Search for patients based on criteria like ID or birth date.

  • query_studies: Find studies using patient ID, date, modality, description, accession number, or Study UID.

  • query_series: Locate series within a specific study using modality, series number/description, or Series UID.

  • query_instances: Find individual instances (images/objects) within a series using instance number or SOP Instance UID

βš™οΈ Utilities

  • list_dicom_nodes: Show the currently active DICOM node, calling AE title, and list all configured nodes.

  • switch_dicom_node: Change the active DICOM node for subsequent operations.

  • verify_connection: Test the DICOM network connection to the currently active node using C-ECHO.

  • get_attribute_presets: List the available attribute presets (none, custom) for metadata query results.

  • get_manifest: Return the MCP tool contract manifest (required/optional tool versions).

Example interaction

The tools can be chained together to answer complex questions:

🀝 Community health

  • Read CONTRIBUTING.md before opening a pull request.

  • Use the issue forms for bugs and focused feature ideas.

  • Follow SECURITY.md for vulnerability reporting.

  • Use SUPPORT.md for setup/help guidance.

  • Do not post PHI, real DICOM studies, or live PACS credentials in issues or PRs.

πŸ“ˆ Contributing

Running Tests

Unit tests run without Orthanc; integration tests require a running Orthanc DICOM server. You can use Docker:

# Navigate to the directory containing docker-compose.yml (e.g., tests/)
cd tests
docker compose up -d

Run unit tests using uv:

# From the project root directory
uv run pytest -m "not integration"

Run integration tests using uv:

# From the project root directory
uv run pytest -m integration

Stop the Orthanc container:

cd tests
docker compose down

Debugging

Use the MCP Inspector for debugging the server communication:

npx @modelcontextprotocol/inspector uv run simple-dicom-mcp /path/to/your_config.yaml --transport stdio

Logging

Set LOG_LEVEL to control verbosity (e.g., DEBUG, INFO, WARNING):

LOG_LEVEL=DEBUG uv run simple-dicom-mcp /path/to/your_config.yaml --transport stdio

Linting, formatting, type checking

uv run ruff check .
uv run ruff format .
uv run pyright

Pre-commit

uv run pre-commit install
uv run pre-commit run --all-files

πŸ™ Acknowledgments

Available Tools

9 tools
get_attribute_presetsA

Get all available attribute presets for DICOM queries.

This tool returns the defined attribute presets that can be used with the query_* functions. It shows which DICOM attributes are included in each preset (none, custom) for each query level.

Returns: Dictionary organized by query level (patient, study, series, instance), with each level containing the attribute presets and their associated DICOM attributes.

Example: { "patient": [ "PatientID", "PatientBirthDate", "PatientSex", "PatientAge", ], "study": [ "StudyInstanceUID", "PatientID", "AccessionNumber", "StudyDescription", "PatientBirthDate", "PatientSex", "PatientAge", "StudyDate", "RequestedProcedureDescription", "RequestedProcedureCodeSequence", ], "series": [ "SeriesInstanceUID", "StudyInstanceUID", "Modality", "SeriesDescription", "BodyPartExamined", "ProtocolName", "RequestAttributesSequence", ], "instance": [ "SOPInstanceUID", "SeriesInstanceUID", ], ... }

Inputs: no named parameters. Returns: result

get_manifestA

Return the MCP manifest for schema/version contract validation.

Inputs: no named parameters. Returns: result

list_dicom_nodesA

List all configured DICOM nodes and their connection information.

This tool returns information about all configured DICOM nodes in the system and shows which node is currently selected for operations. It also provides registry metadata used by downstream node resolvers.

Returns: Dictionary containing: - current_node: The currently selected DICOM node name - current_calling_aet: The currently selected calling AE name or AE title - current_calling_ae_title: The resolved calling AE title in use - nodes: List of node registry entries with canonical name, AE title, and optional aliases/description - nodes_legacy: Backward-compatible list of {name: description} - calling_aets: List of configured calling AE entries (if any)

Example: { "current_node": "pacs1", "current_calling_aet": "default", "current_calling_ae_title": "MCPSCU", "nodes": [ { "name": "pacs1", "ae_title": "PACS1", "aliases": ["main", "primary"], "description": "Primary PACS", }, { "name": "orthanc", "ae_title": "ORTHANC", }, ], "nodes_legacy": [ {"pacs1": "Primary PACS"}, {"orthanc": ""}, ], "calling_aets": [ { "name": "default", "ae_title": "MCPSCU", "description": "Default calling AE", } ], }

Inputs: no named parameters. Returns: result

query_instancesA

Query individual DICOM instances (images) within a series.

This tool performs a DICOM C-FIND operation at the IMAGE level to find individual DICOM instances within a specified series. The series_instance_uid is required, and additional parameters can be used to filter the results.

Args: series_instance_uid: Unique identifier for the series (required) instance_number: Filter by specific instance number within the series sop_instance_uid: Unique identifier for a specific instance attribute_preset: Controls which attributes to include in results: - "none": No attributes, use with additional_attributes (default) - "custom": Our custom attributes additional_attributes: List of specific DICOM attributes to include beyond the preset exclude_attributes: List of DICOM attributes to exclude from the results

Returns: Dictionary containing query results and status metadata. The results list includes entries like: { "SOPInstanceUID": "1.2.840.113619.2.1.1.322.1600364094.412.3001", "SOPClassUID": "1.2.840.10008.5.1.4.1.1.2", "InstanceNumber": "45", "ContentDate": "20230215", "ContentTime": "152245" }

Notes: Returns success False if the query fails.

Inputs: series_instance_uid (required), instance_number, sop_instance_uid, attribute_preset, +2 more. Returns: result

query_patientsA

Query patients matching the specified criteria from the DICOM node.

This tool performs a DICOM C-FIND operation at the PATIENT level to find patients matching the provided search criteria. All search parameters are optional and can be combined for more specific queries.

Args: patient_id: Patient ID to search for, e.g., "12345678" birth_date: Patient birth date in YYYYMMDD format, e.g., "19700101" attribute_preset: Controls which attributes to include in results: - "none": No attributes, use with additional_attributes (default) - "custom": Our custom attributes additional_attributes: List of specific DICOM attributes to include beyond the preset exclude_attributes: List of DICOM attributes to exclude from the results

Returns: Dictionary containing: - success: Boolean indicating if the query completed without failure - results: List of matched patient records - dicom_statuses: List of DICOM status entries - warnings: List of warning entries - error: Optional error dictionary

Example: { "success": true, "results": [ { "PatientID": "12345", "PatientBirthDate": "19700101", "PatientSex": "M" } ], "dicom_statuses": [{"code": "0x0000", "category": "success"}], "warnings": [], "error": null }

Notes: Returns success False if the query fails.

Inputs: patient_id, birth_date, attribute_preset, additional_attributes, +1 more. Returns: result

query_seriesA

Query series within a study from the DICOM node.

This tool performs a DICOM C-FIND operation at the SERIES level to find series within a specified study. The study_instance_uid is required, and additional parameters can be used to filter the results.

Args: study_instance_uid: Unique identifier for the study (required) modality: Filter by imaging modality, e.g., "CT", "MR", "US", "CR" series_number: Filter by series number series_description: Series description text with wildcards. IMPORTANT: Use wildcards on BOTH sides for substring matching, e.g., "AXIAL" to find "AXIAL 2.5MM RECON". Using "AXIAL*" only matches descriptions starting with "AXIAL". series_instance_uid: Unique identifier for a specific series limit: Maximum number of results to return (None = no limit) attribute_preset: Controls which attributes to include in results: - "none": No attributes, use with additional_attributes (default) - "custom": Our custom attributes additional_attributes: List of specific DICOM attributes to include beyond the preset exclude_attributes: List of DICOM attributes to exclude from the results

Returns: Dictionary containing query results and status metadata. The results list includes entries like: { "SeriesInstanceUID": "1.2.840.113619.2.1.1.322.1600364094.412.2005", "SeriesNumber": "2", "SeriesDescription": "AXIAL 2.5MM", "Modality": "CT", "NumberOfSeriesRelatedInstances": "120" }

Notes: Returns success False if the query fails.

Inputs: study_instance_uid (required), modality, series_number, series_description, +5 more. Returns: result

query_studiesA

Query studies matching the specified criteria from the DICOM node.

This tool performs a DICOM C-FIND operation at the STUDY level to find studies matching the provided search criteria. All search parameters are optional and can be combined for more specific queries.

Args: patient_id: Patient ID to search for (supports wildcards), e.g., "12345678" or "123" patient_sex: Patient sex (F, M, O) patient_birth_date: Patient birth date or range in DICOM format: - Single date: "19700101" - Date range: "19700101-19801231" study_date: Study date or date range in DICOM format: - Single date: "20230101" - Date range: "20230101-20230131" modality_in_study: Filter by modalities present in study, e.g., "CT" or "MR" study_description: Study description text with wildcards. IMPORTANT: Use wildcards on BOTH sides for substring matching, e.g., "CHEST" to find "CT CHEST W CONTRAST". Using "CHEST*" only matches descriptions starting with "CHEST". accession_number: Medical record accession number (supports wildcards) study_instance_uid: Unique identifier for a specific study limit: Maximum number of results to return (None = no limit) attribute_preset: Controls which attributes to include in results: - "none": No attributes, use with additional_attributes (default) - "custom": Our custom attributes additional_attributes: List of specific DICOM attributes to include beyond the preset exclude_attributes: List of DICOM attributes to exclude from the results filters: Dictionary of DICOM tag names to filter values. Use this to filter by any DICOM attribute not in the standard parameters. Supports wildcards. Example: {"RequestedProcedureDescription": "CHESTANGIO*"}

Returns: Dictionary containing query results and status metadata. The results list includes entries like: { "StudyInstanceUID": "1.2.840.113619.2.1.1.322.1600364094.412.1009", "StudyDate": "20230215", "StudyDescription": "CHEST CT", "PatientID": "12345", "ModalitiesInStudy": "CT" }

Notes: Returns success False if the query fails.

Inputs: patient_id, patient_sex, patient_birth_date, study_date, +9 more. Returns: result

switch_dicom_nodeA

Switch the active DICOM node connection to a different configured node.

This tool changes which DICOM node (PACS, workstation, etc.) subsequent operations will connect to. The node must be defined in the configuration file.

Args: node_name: The name of the node to switch to, must match a name in the configuration

Returns: Dictionary containing: - success: Boolean indicating if the switch was successful - message: Description of the operation result or error

Example: { "success": true, "message": "Switched to DICOM node: orthanc" }

Notes: Returns success False if the node name is not found.

Inputs: node_name (required). Returns: result

verify_connectionA

Verify connectivity to the DICOM node using C-ECHO.

This tool performs a DICOM C-ECHO operation (similar to a network ping) to check if the currently selected DICOM node is reachable and responds correctly. This is useful to troubleshoot connection issues before attempting other operations.

Returns: Dictionary containing: - success: Boolean indicating if the connection succeeded - message: Description of the connection status - details: Connection details (node, host, port, AE titles)

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct aspect: attribute presets, manifest, node listing, four query levels, node switching, and connection verification. No overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_, list_, query_, switch_, verify_) in snake_case, making them predictable and easy to differentiate.

    Tool Count5/5

    9 tools is well-scoped for a DICOM MCP server: four query tools for different imaging levels, plus configuration and connection management.

    Completeness4/5

    The surface covers querying at all four DICOM levels and node management, but lacks instance retrieval (C-MOVE/C-GET) or data export, which may be expected but are outside a 'simple' scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      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.
      108
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query, read, download, and move medical imaging data on DICOM servers (PACS, VNA) including patient searches, study retrieval, PDF report extraction, and image transfer to AI endpoints for analysis.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that exposes a DICOMweb-compliant DICOM archive to AI assistants. It lets any MCP-capable client search studies, series and instances, inspect metadata, read Structured and Encapsulated PDF Reports, and render image frames β€” all through natural language.
      9
      51 npm
      4
      MIT