Skip to main content
Glama
rt-imaging-mcp

rt-imaging-mcp

by MLwithDyy

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.

Related MCP server: DICOM API MCP Server

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

Available Tools

4 tools
dicom_get_metadataRead allowlisted DICOM metadataA
Read-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 keywordsA
Read-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 seriesA
Read-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 informationA
Read-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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      108
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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