DICOM Agent

dicom-agent-mcp

An MCP (Model Context Protocol) server that gives AI agents one set of tools for both DIMSE archives (C-ECHO, C-FIND, C-GET, C-MOVE, C-STORE) and DICOMweb archives (QIDO-RS, WADO-RS, STOW-RS).

It also includes pixel and geometry tools that work on local files: rendering, statistics, measurement, geometry checks, multiplanar reconstruction (MPR) and de-identification. This is the tool layer for Topic 3 (Validated Tool Execution). The verification loop comes later; see ROADMAP.md.

Not for clinical use. This is a research scaffold. Use only with test or de-identified data.

Tools

Pixel and geometry tools (local files)

Every pixel result includes an input_fingerprint: a SHA-256 hash of the decoded pixels and geometry. It does not change with the transfer syntax, and the verification loop uses it to bind results to their inputs.

Verification tools

See Verification loop.

Each tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so a harness can decide which tools need approval.

Install

python -m venv .venv

.venv\Scripts\python -m pip install -e ".[dev]"

Optional: decoders for JPEG, JPEG-LS, JPEG 2000 and RLE compressed pixel data

.venv\Scripts\python -m pip install -e ".[codecs]"

Configure

No config file is needed. Pass nodes and paths as arguments in the harness config; add a YAML file only for advanced settings.

Arguments

Node spec: name=URL[;option;option…]

Examples:

--node orthanc=dimse://ORTHANC@localhost:4242

--node orthanc-web=http://localhost:8042/dicom-web --node "azure=https:// - .dicom.azurehealthcareapis.com/v2;token-env=AZURE_DICOM_TOKEN;read-only"

Secrets never go in arguments. Arguments are visible in process lists and are often committed in mcp.json. Put tokens and passwords in environment variables and pass only the variable name.

With no --node, the server still starts: the local-file and pixel tools work on files under the allowed paths.

Environment variables

Every argument has an environment-variable equivalent, which suits Docker and CI:

Optional YAML file (advanced)

Use a file for settings that have no argument: timeouts, max_results, max_volume_voxels, deid_key_env and node descriptions. See config.example.yaml. If ./dicom-agent-mcp.yaml exists in the working directory, it is loaded automatically. Relative paths in a file resolve against the file's directory; relative paths in arguments and environment variables resolve against the working directory.

Precedence: config file, then environment variables, then arguments. Later sources override single values, nodes are merged by name (a --node with the same name replaces the file's node), and allowed paths are combined.

Run

dicom-agent-mcp --node orthanc=dimse://ORTHANC@localhost:4242                                   # stdio

dicom-agent-mcp --node orthanc=dimse://ORTHANC@localhost:4242 --transport streamable-http --port 8000 dicom-agent-mcp --node orthanc=dimse://ORTHANC@localhost:4242 --print-config # check settings

VS Code (.vscode/mcp.json)

{

"inputs": [ { "id": "azureToken", "type": "promptString", "description": "Azure DICOM access token", "password": true } ], "servers": { "dicom": { "type": "stdio", "command": "${workspaceFolder}/.venv/Scripts/dicom-agent-mcp", "args": [ "--node", "orthanc=dimse://ORTHANC@localhost:4242", "--node", "orthanc-web=http://localhost:8042/dicom-web", "--node", "azure=https:// - .dicom.azurehealthcareapis.com/v2;token-env=AZURE_DICOM_TOKEN;read-only", "--storage-dir", "${workspaceFolder}/dicom-cache", "--allow-path", "${workspaceFolder}/inbox" ], "env": { "AZURE_DICOM_TOKEN": "${input:azureToken}" } } } }

Claude Desktop / Copilot CLI / other harnesses

{

"mcpServers": { "dicom": { "command": "dicom-agent-mcp", "args": [ "--node", "orthanc=dimse://ORTHANC@localhost:4242", "--allow-path", "C:/data/dicom-inbox" ] } } }

Use absolute paths here: these harnesses may start the server in any working directory. To use a file instead, pass "args": ["--config", "C:/path/to/dicom-agent-mcp.yaml"].

Local Orthanc for testing

docker-compose up -d   # DIMSE on 4242, DICOMweb on http://localhost:8042/dicom-web (compose file not yet tested)

Sample prompts

These prompts assume three nodes: orthanc (DIMSE), orthanc-web (DICOMweb) and azure-dicom, for example:

--node orthanc=dimse://ORTHANC@localhost:4242 --node orthanc-web=http://localhost:8042/dicom-web

--node "azure-dicom=https:// - .dicom.azurehealthcareapis.com/v2;token-env=AZURE_DICOM_TOKEN"

The tool the agent is expected to call is shown after each prompt.

Nodes and connectivity

Search and metadata

Moving data

Local files

Pixels and geometry

De-identification

| "De-identify it but k