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 planned verification loop will use it to bind results to their inputs.

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://<workspace>-<service>.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                                   # stdiodicom-agent-mcp --node orthanc=dimse://ORTHANC@localhost:4242 --transport streamable-http --port 8000dicom-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://<workspace>-<service>.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://<workspace>-<service>.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

Multi-step workflows

• "Find the latest CT for patient MRN123 on orthanc, download it, check its geometry, and show me an axial and a coronal view in a soft-tissue window."
• "Measure the mean HU of the liver at slice 60 (a 15 mm circle at row 300, column 180) and report the input fingerprint."
• "Download study X from orthanc, de-identify it, and upload the de-identified copy to azure-dicom."

Prompts the server should refuse

Safety

• Path sandbox. store, list_local_files, read_local_metadata and the pixel tools only accept paths under storage_dir or allowed_paths.
• UID validation. UIDs are checked before they are used in file paths or URLs.
• read_only nodes. store, move and transfer refuse to write to them.
• Result caps. max_results limits results; truncation is reported with truncated: true.
• Pixels in context only by request. Raw pixel arrays are never returned. render_image and render_mpr do send a downsampled PNG to the model; a copy is saved under storage_dir/renders.
• Volume cap. render_mpr refuses series larger than max_volume_voxels, and refuses series that fail check_geometry.

De-identification

deidentify does the following:

• removes or empties identifying attributes;
• drops private tags and overlay or curve groups;
• replaces PatientName and PatientID with pseudonyms;
• remaps instance UIDs consistently;
• by default, shifts dates by a per-patient offset of 1 to 730 days.

It records what it did in DeidentificationMethodCodeSequence.

To get the same pseudonyms and UIDs across runs, set a secret key in the environment variable named by deid_key_env (default DICOM_AGENT_MCP_DEID_KEY). Without a key, each call uses a random key and the result reports linkable: false.

It does not remove text burned into the pixels; affected modalities produce a warning. It is a research aid, not a certified de-identification tool.

Architecture

server.py  (FastMCP tools)  →  service.py  (routing, sandbox, paging)                                   ├── dimse.py     (pynetdicom SCU)                                   ├── dicomweb.py  (httpx QIDO/WADO/STOW)                                   ├── imaging.py   (windowing, geometry, ROI stats, MPR, fingerprints)                                   └── deid.py      (Basic Profile subset)

Tests

.venv\Scripts\python -m pytest -q

The tests run end to end against an in-process pynetdicom PACS (two AEs so C-MOVE can be tested) and a mocked DICOMweb server. They need no network. The pixel tests use a synthetic CT series with known HU values, spacing and positions.

Limitations

• STOW-RS builds the whole request in memory, and WADO-RS reads the whole response into memory.
• DIMSE get_metadata only returns attributes that the archive indexes for C-FIND.
• retrieve uses C-GET. Archives that only support C-MOVE need move to a storage SCP.
• No TLS for DIMSE yet.
• Pixel tools have been tested on synthetic CT and pydicom sample files only. Compressed transfer syntaxes, enhanced multi-frame objects and real-world data are not yet tested.
• MPR uses nearest-slice sampling and does not resample to isotropic voxels.
• Pixel tools work on local files; use retrieve first.

Roadmap

See ROADMAP.md.