rt-imaging-mcp
This read-only MCP server lets AI agents inspect local DICOM and NIfTI files with limited, PHI-safe output and root-confined access.
Scan directories for DICOM series and return opaque series IDs, modality, instance counts, and image size; optionally omit file/directory names.
Read allowlisted technical metadata from one DICOM file, such as geometry, bit depth, modality, and transfer syntax, without patient identifiers or pixel data.
List the DICOM attribute keywords that metadata reads may currently return.
Read structural NIfTI header information: shape, voxel size, data type, units, and orientation, without free-text header fields or image data.
Operate read-only with bounded work, no writes, and no network access.
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., "@rt-imaging-mcp scan the image directory for DICOM series and summarize the modalities"
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.
rt-imaging-mcp
A local, read-only Model Context Protocol server that lets AI agents inspect medical image files (DICOM, NIfTI) on your own disk, with PHI-safe output by default.
Status: early development (pre-alpha). DICOM scanning, allowlisted DICOM metadata, NIfTI header information, RTSTRUCT, RTDOSE and RTPLAN summaries and approximate dose-volume metrics work today. Radiomics is planned, not implemented. Dose-volume results are validated on synthetic phantoms only, not against a planning system.
Read this first
Research use only. Not a medical device. Not for clinical use.
Running locally does not by itself keep data private. Tool output is sent to the model your MCP client uses. If that model is hosted in the cloud, so is every tool result. This project limits what tools return (see docs/threat-model.md) but cannot guarantee anonymity.
For full privacy, use a locally hosted model. Never use real patient data for development or testing.
Related MCP server: DICOM API MCP Server
Tools
Tool | What it returns |
| Inventory of DICOM series below a directory: opaque series ids, modality, instance counts, image size, file counts. No UIDs. |
| Allowlisted technical attributes of one DICOM file (geometry, bit depth, modality, transfer syntax, ...). |
| The attribute keywords |
| Shape, voxel size, data type, units and orientation from the NIfTI header. Free-text header fields are never returned. |
| RTDOSE grid: dose type and units, grid size, voxel size, whole-grid maximum and mean dose, non-zero voxel count. No dose array, no grid position. |
| RTPLAN: intent, approval status, fractions, one entry per beam (type, radiation, energy, angles, dose, meterset) and prescription doses. No plan, beam or machine names. |
| Dose statistics, D(p) and V(t) for one structure of an RTSTRUCT on an RTDOSE grid (for example D95, D2, V20 Gy). Approximate; refuses mismatched frames of reference. |
| One entry per RTSTRUCT structure: interpreted type, contour and slice counts, extent, approximate planar volume. Names are returned only if standard (TG-263 style), otherwise |
All tools are read-only and are declared as such to the client.
Safety design
Tag allowlist. Only listed attributes can be returned. Patient name, ID, birth date, institution, physician names, accession number, private tags and similar are blocked and cannot be enabled. Dates, descriptions and UIDs are off by default and need an explicit
--enable-tagby the human operator (not the agent).Structure names are standardised. RTSTRUCT names are free text and can contain identifiers, so only standard names (a TG-263-style subset) and fixed-token target names such as
PTV_Highare returned; others arenull.RT dose and plan output is numbers and enumerated codes only. Plan, beam and machine names, reviewer names and other free text are never returned.
Dose-volume metrics refuse inconsistent input. The structure set and dose must share a frame of reference and use a supported grid; results are labelled approximate and computation is bounded.
No pixel data, ever (the dose grid is read to compute statistics and is never returned).
One root directory. The server refuses to start without
--root(orRT_IMAGING_MCP_ROOT)..., absolute paths outside the root and symlinks that leave the root are rejected.Static error messages. Errors never quote data read from files.
Bounded work. Limits on file count, directory depth and file size.
No writes, no network. Enforced by a static test on the source.
Known limits are listed in the threat model. In short: file and folder names are controlled by you and can contain
identifiers (use opaque_paths=true to omit them), and prompt injection through file content cannot be fully prevented.
Validation
Dose-volume metrics are checked against hand-calculated phantoms and against dicompyler-core on synthetic data. They are not validated against a treatment planning system or real patient data yet. See docs/validation.md for the numbers, the differences and how to reproduce them.
Install and run
Requires Python 3.11+ and uv.
git clone https://github.com/MLwithDyy/rt-imaging-mcp
cd rt-imaging-mcp
uv sync
uv run rt-imaging-mcp --root /path/to/de-identified/imagesOptions: --enable-tag KEYWORD (repeatable, opt-in DICOM attributes), --enable-roi-name NAME (repeatable, extra
structure names to return), --max-files, --max-depth, --max-file-mb.
Claude Code
claude mcp add rt-imaging -- uv run --directory /path/to/rt-imaging-mcp rt-imaging-mcp --root /path/to/imagesClaude Desktop (and other clients using a JSON config)
{
"mcpServers": {
"rt-imaging": {
"command": "uv",
"args": [
"run", "--directory", "/path/to/rt-imaging-mcp",
"rt-imaging-mcp", "--root", "/path/to/images"
]
}
}
}On Windows, escape backslashes in JSON (D:\\Project\\rt-imaging-mcp) or use forward slashes.
Debug with the MCP Inspector:
npx @modelcontextprotocol/inspector uv run rt-imaging-mcp --root /path/to/imagesDevelopment
uv sync
uv run pytest
uv run ruff check .
uv run mypy
pre-commit installTests use synthetic data generated at run time. Medical image files are blocked from commits by .gitignore
and a pre-commit hook. Do not attach real patient data to issues or pull requests.
Roadmap
DICOM and NIfTI basics (done, pre-alpha)
CI on Python 3.11-3.13, Linux and Windows (done)
Radiotherapy objects: RTSTRUCT, RTDOSE and RTPLAN summaries and approximate DVH metrics (done)
Radiomics feature extraction with validation against IBSI reference data
Release to PyPI
Related work
dicom-mcp connects agents to DICOM network servers (PACS). This project
is complementary: it works on local files and focuses on PHI-safe output, radiotherapy objects and radiomics.
Contributing and security
See CONTRIBUTING.md. Never attach real patient data to issues or pull requests. Report vulnerabilities privately as described in SECURITY.md.
License
Available Tools
4 toolsdicom_get_metadataRead allowlisted DICOM metadataARead-onlyIdempotent
Read allowlisted technical attributes of one DICOM file (path relative to the root).
Use dicom_list_allowed_tags to see which keywords are allowed. Requesting any other keyword fails. Patient identifiers and pixel data are never returned.
Inputs: path (required), keywords. Returns: object
dicom_list_allowed_tagsList allowed DICOM attribute keywordsARead-onlyIdempotent
List the DICOM attribute keywords that dicom_get_metadata can currently return.
Inputs: no named parameters. Returns: object
dicom_scan_directoryScan a directory for DICOM seriesARead-onlyIdempotent
Inventory DICOM series below a directory (path relative to the root).
Returns opaque series ids, modality, instance counts and image size. Study and series UIDs are never returned. Set opaque_paths=True to omit all file and directory names. Only DICOM Part 10 files (with the DICM preamble) are detected.
Inputs: directory, opaque_paths. Returns: object
nifti_infoRead NIfTI header informationARead-onlyIdempotent
Return shape, voxel size, data type, units and orientation of a NIfTI file.
Only structural header fields are returned. Free-text header fields and the image data are never read into the output.
Inputs: path (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: one reads single-file DICOM metadata, one scans directories, one lists allowed DICOM tags, and one inspects NIfTI headers. The helper/listing tool is explicitly framed as supporting the metadata tool, so boundaries remain clear.
Three tools follow a consistent dicom_verb_noun pattern, while nifti_info follows a separate modality prefix and uses a noun-style name rather than a verb. The pattern is still highly readable and mostly predictable across the set.
Four tools is well-scoped for a narrow, read-only imaging metadata server. Each tool earns its place by covering a specific inspection need without adding redundant operations.
The DICOM side covers directory inventory, allowed-tag discovery, and metadata retrieval, and the NIfTI side covers header inspection. Minor gaps exist, such as no equivalent inventory operation for NIfTI files, but the core read-only metadata purpose is covered.
Maintenance
Related MCP Connectors
Safety tools for AI agents: safe page reader, prompt-injection, secrets, PII and MCP server scans
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Trust signals for AI agents: an open agent-readiness standard and developer tool guide. Read-only.
Read-only tools over the Safer Agentic AI framework: 239 patterns + 15 heuristics.
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
- 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.-
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to perform end-to-end medical image analysis locally, from inspecting CT/MRI/X-ray studies and running containerized segmentation models like MedSAM2, TotalSegmentator, and HD-BET to refining masks, measuring volumes, and writing reports. It pairs preset or custom guideline protocols with a code-customizable viewer that renders images back to agents as annotated PNGs and to humans as interactive HTML.2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables LLM agents to query de-identified FHIR-shaped hospital data through audited, read-only tools for patients, encounters, conditions, observations, medications, and interaction checks, while any medication write stays a draft that a clinician must confirm out-of-band.MIT