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.
Tools
| Tool | What it returns |
|---|---|
dicom_scan_directory |
Inventory of DICOM series below a directory: opaque series ids, modality, instance counts, image size, file counts. No UIDs. |
dicom_get_metadata |
Allowlisted technical attributes of one DICOM file (geometry, bit depth, modality, transfer syntax, ...). |
dicom_list_allowed_tags |
The attribute keywords dicom_get_metadata may currently return. |
nifti_info |
Shape, voxel size, data type, units and orientation from the NIfTI header. Free-text header fields are never returned. |
rt_dose_summary |
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. |
rt_plan_summary |
RTPLAN: intent, approval status, fractions, one entry per beam (type, radiation, energy, angles, dose, meterset) and prescription doses. No plan, beam or machine names. |
rt_dvh_metrics |
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. |
rt_structure_summary |
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 null. |
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, against dicompyler-core on synthetic data, and against dicompyler-core on three patients of one public collection (preliminary: volume, mean dose, D50 and D2 agree on all 39 structures within the stated tolerances; a few D95 and V(t) differences are unexplained). They are not validated against a treatment planning system. See docs/validation.md for the numbers, the differences and how to reproduce them.
Install and run
Requires Python 3.11+ and uv.
Install from PyPI
uvx rt-imaging-mcp --root /path/to/de-identified/images
For Claude Code:
claude mcp add rt-imaging -- uvx rt-imaging-mcp --root /path/to/images
Install from source
git clone [https://github.com/MLwithDyy/rt-imaging-mcp](https://github.com/MLwithDyy/rt-imaging-mcp)
cd rt-imaging-mcp
uv sync
uv run rt-imaging-mcp --root /path/to/de-identified/images
Options: --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 (from source)
claude mcp add rt-imaging -- uv run --directory /path/to/rt-imaging-mcp rt-imaging-mcp --root /path/to/images
Claude 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/images
Development
uv sync
uv run pytest
uv run ruff check .
uv run mypy
pre-commit install
Tests 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 (done)
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
Metadata
Release files for rt-imaging-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rt_imaging_mcp-0.1.1.tar.gz | 193.0 kB | With provenance | Details for rt_imaging_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rt_imaging_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for rt_imaging_mcp-0.1.1-py3-none-any.whl |
Total release size: 233.7 kB
Release files / rt_imaging_mcp-0.1.1.tar.gz
| Download URL | rt_imaging_mcp-0.1.1.tar.gz |
|---|---|
| Size | 193.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52839c0f2a7a7b718472b81afee6f238430deec2b736600107745ff95d204e02
|
|
BLAKE2b-256 checksum How to use checksums |
7f07318f64edfd230debd25a1681e3ce92b52ec2d65c852d37d76830f83d5e16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / rt_imaging_mcp-0.1.1-py3-none-any.whl
| Download URL | rt_imaging_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 40.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11414e744f229cce037fd4c42746275bf12cfcab279300db66428781344c50fa
|
|
BLAKE2b-256 checksum How to use checksums |
0b8a3b922bab795f8b5ea07d82b273d7c3afd4cab78c638ea5cccd8f42148f6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for rt-imaging-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rt_imaging_mcp-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.