simple-dicom-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@simple-dicom-mcp find studies for patient ID 12345"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.yamlIf uv caches old code: add
--no-cacheor--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
localhostworks 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_connectionRegistry:
get_manifestQuery:
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-cacheor--reinstall-package simple-dicom-mcp.On WSL/Windows, enable mirrored networking so
localhostworks across Windows and WSL.
License & credit
MIT license (see LICENSE)
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-mcpOr 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_aetcan be a name, alias, or AE title defined incalling_aets.query_rootacceptsstudyorpatient.allow_remote_hostsdefaults tofalseand blocks non-loopback DICOM hosts unless you explicitly opt in.
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 integrationUI 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.mdbefore opening a pull request.Use the issue forms for bugs and focused feature ideas.
Follow
SECURITY.mdfor vulnerability reporting.Use
SUPPORT.mdfor 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 -dRun 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 integrationStop the Orthanc container:
cd tests
docker compose downDebugging
Use the MCP Inspector for debugging the server communication:
npx @modelcontextprotocol/inspector uv run simple-dicom-mcp /path/to/your_config.yaml --transport stdioLogging
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 stdioLinting, formatting, type checking
uv run ruff check .
uv run ruff format .
uv run pyrightPre-commit
uv run pre-commit install
uv run pre-commit run --all-filesπ Acknowledgments
Built using pynetdicom
Available Tools
9 toolsget_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
Scored across 9 tools
Each tool targets a distinct aspect: attribute presets, manifest, node listing, four query levels, node switching, and connection verification. No overlapping purposes.
All tool names follow a consistent verb_noun pattern (get_, list_, query_, switch_, verify_) in snake_case, making them predictable and easy to differentiate.
9 tools is well-scoped for a DICOM MCP server: four query tools for different imaging levels, plus configuration and connection management.
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
Related MCP Connectors
Connect AI clients to biomedical data and tools.
Read patient-authorized EHR records: medications, labs, conditions, allergies. Consent-bounded.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
Query Health Gorilla FHIR patients, conditions, medications and lab results.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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.108MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceExposes DICOM operations as tools for AI agents to interact with medical imaging systems and PACS. It enables searching for studies and series, querying instance metadata, and retrieving pixel data from DICOM entities.-
- AlicenseAqualityBmaintenanceAn 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.951 npm4MIT