Skip to main content

rt-imaging-mcp

CI

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-tag by 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_High are returned; others are null.
  • 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 (or RT_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.

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/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

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

  1. DICOM and NIfTI basics (done, pre-alpha)
  2. CI on Python 3.11-3.13, Linux and Windows (done)
  3. Radiotherapy objects: RTSTRUCT, RTDOSE and RTPLAN summaries and approximate DVH metrics (done)
  4. Radiomics feature extraction with validation against IBSI reference data
  5. Release to PyPI

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

Apache-2.0. See LICENSE and NOTICE.

Metadata

Release files for rt-imaging-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rt-imaging-mcp 0.1.0
File Size Uploaded Provenance Actions
rt_imaging_mcp-0.1.0.tar.gz 191.8 kB With provenance Details for rt_imaging_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rt-imaging-mcp 0.1.0
File Interpreter ABI Platform Actions
rt_imaging_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for rt_imaging_mcp-0.1.0-py3-none-any.whl

Total release size: 232.4 kB

Release files / rt_imaging_mcp-0.1.0.tar.gz

Download URL rt_imaging_mcp-0.1.0.tar.gz
Size 191.8 kB
Tags Source
SHA-256 checksum
How to use checksums
63a56df2acc45eadcda112d46cdce1d01de377e3413bb3d9358ae9b895811a5d
BLAKE2b-256 checksum
How to use checksums
35aa8176c2b17a3526da08b9f97935efb559e6f7ea3da779e20be0413969d007
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 19, 2026.

Transparency log

Release files / rt_imaging_mcp-0.1.0-py3-none-any.whl

Download URL rt_imaging_mcp-0.1.0-py3-none-any.whl
Size 40.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
98e995c00949917d41eefec0015526630f9353689bccd18e54b02c363f7e83c0
BLAKE2b-256 checksum
How to use checksums
5e347069ca43393d85f84a2f1335c92c901de1a58ad5902c04fed236dc33db53
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 19, 2026.

Transparency log

Security for rt-imaging-mcp 0.1.0

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.

Select from 2 files

Attestation for rt_imaging_mcp-0.1.0.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 19, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page