Install

uv tool install --python 3.13 "medmlx[all,mcp]"

For a Python project, use uv add "medmlx[all,mcp]". Run uv tool upgrade medmlx to update MedMLX and its models. Model weights download on first use and keep their own terms. For a smaller install, replace all with one group:

Extra	Installs
all	Every model runtime, with Reason-CT tools
segment	Segmentation runtimes, including SAM 3 video
generate	Reason-CT, NV-Generate, LesionDiffusion and FDG PET synthesis
vision	Lung nodule detection, RadImageNet features and radiomics
mcp	The MCP server

Quickstart

medmlx models lists the installed models. To segment a CT scan, put it in a working folder and run from there:

mkdir -p ~/medmlx-work && cd ~/medmlx-work
cp /path/to/ct.nii.gz .

Then show the model's arguments, check that it can run, and run it:

medmlx describe mlx-segment-ct
medmlx readiness mlx-segment-ct --arg image_path=ct.nii.gz output_dir=segment-ct
medmlx run mlx-segment-ct --arg image_path=ct.nii.gz output_dir=segment-ct

• --arg takes the argument names describe lists. Values are converted to the declared types; give lists and other JSON values as KEY:=JSON, for example points:='[[120, 140, 60]]'. --arguments FILE reads them from a JSON file.
• Relative paths resolve against the current folder, or against --root.
• readiness checks Metal and the input paths without downloading anything.
• The first run downloads the MedMLX/vista3d-ct-mlx weights; later runs reuse the cache.
• The mask is written to segment-ct/mlx_segment_ct_mask.nii.gz.
• medmlx setup --all --progress downloads every model's weights for offline use. See automatic weights and readiness.

Models

Model IDs are what medmlx run and medmlx describe take.

Model ID	Task	Input	Extra
musclemap	113 muscle and bone structures	MRI, CT	segment
totalsegmentator	Whole-body CT segmentation	CT	segment
mlx-segment-ct, mlx-segment-ctmr	Automatic and point-prompted segmentation (VISTA-3D)	CT, MRI	segment
nnunet-liver, nnunet-pancreas, nnunet-autopet, nnunet-brats2021	Organ and tumor segmentation (nnU-Net v2)	CT, PET/CT, brain MRI	segment
mrsegmentator	Multi-organ MRI segmentation	MRI	segment
siam	Whole-head segmentation from any MRI contrast or CT	Head MRI, CT	segment
synthseg	Brain segmentation and parcellation	Brain MRI, CT	segment
medsam2	Box-, point- or mask-prompted masks with propagation	NIfTI slices or volumes, frames	segment
sam3	Text-, box- or point-prompted image segmentation	2D images, video frames	segment
biomedparse-v2	Text-prompted segmentation	3D volumes, 2D images	segment
swin-unetr	13 abdominal organs	Contrast CT	segment
segresnet-renal-cect	Renal arteries, veins, ureters, tumors and parenchyma	Multiphase CT	segment
unest	Kidney cortex, medulla and collecting system	CT	segment
flexray	Radiograph anatomy	Radiographs	segment
flexible-unet	Surgical tools	Endoscopy frames	segment
lung-nodule	Lung nodule detection	Chest CT	vision
radimagenet-*	Radiology image features	2D images	vision
mlx-reason-ct	CT reports and question answering	CT	generate
reason-ct-tools	Reason-CT with nodule detection and MedSAM2 masks	Chest CT	reason-tools
mlx-generate-ctmr-ct, -mr, -mr-brain	Synthetic CT and MRI	Label maps or anatomy	generate
lesiondiffusion	Synthetic CT lesions	CT and organ mask	generate
fdg-pet-ct	Synthetic FDG PET (weight-free)	CT and labels	generate
medgemma	Image-to-text through a separate environment	2D images	bridge

Each model has its own repository in the MedMLX organization. medgemma and mrsegmentator require local weights.

Memory

MedMLX runs one model at a time by default. It never refuses a run for memory: readiness reports a model's peak next to the memory available, and the run starts either way, so a Mac with too little memory may swap or fail. Declared peaks:

Model	Peak MLX memory
siam	16 GB
nnunet-pancreas	14.5 GB
mlx-reason-ct	12.5 GB
synthseg	11.6 GB
mlx-generate-ctmr-ct	11.1 GB
mlx-segment-ctmr	11.0 GB
lung-nodule	10.8 GB
mlx-generate-ctmr-mr, mlx-generate-ctmr-mr-brain	10.2 GB
nnunet-liver	9.0 GB
swin-unetr, nnunet-brats2021	7.5 GB
unest	7.3 GB
mlx-segment-ct	6.0 GB
sam3	5.4 GB
totalsegmentator	5.0 GB
nnunet-autopet	4.8 GB
segresnet-renal-cect	4.1 GB
biomedparse-v2	3.9 GB
lesiondiffusion	3.5 GB
fdg-pet-ct	2.8 GB
medsam2	1.3 GB
flexray	1.2 GB
radimagenet-*, flexible-unet	0.5 GB or less

Models without a declared peak, such as mrsegmentator, record their measured peak after each run, and medmlx describe reports it.

medgemma runs in its own interpreter, outside this check. Describing a chest radiograph peaks at 4.4 GB with MedGemma 1.5 4B and 17.9 GB with MedGemma 27B.

MCP

medmlx serve --root /path/to/work runs a stdio MCP server that lets an assistant list models, check inputs and run jobs in that folder. For Claude Code:

mkdir -p ~/medmlx-work
claude mcp add --scope user medmlx -- "$(uv tool dir --bin)/medmlx" serve --root "$HOME/medmlx-work"

For clients configured with JSON, use absolute paths:

{
  "mcpServers": {
    "medmlx": {
      "command": "/absolute/path/to/medmlx",
      "args": ["serve", "--root", "/absolute/path/to/medmlx-work"]
    }
  }
}

Disconnecting the client cancels its running jobs. The MCP guide covers Codex, other clients, tools and a complete job workflow.

Python

import medmlx

result = medmlx.run(
    "mlx-segment-ct",
    arguments={"image_path": "ct.nii.gz", "output_dir": "segment-ct"},
    root="/path/to/medmlx-work",
)

For a model declaring a cohort adapter, queue up to 256 cases with one prepared model. The liver adapter supports this explicitly:

with medmlx.start_cohort(
    "nnunet-liver",
    preparation={"weights_path": "liver-model"},
    cases=[
        {"image_path": "ct-a.nii.gz", "output_dir": "out-a"},
        {"image_path": "ct-b.nii.gz", "output_dir": "out-b"},
    ],
) as cohort:
    cases = cohort.wait()["result"]["cases"]

Cases run in order and report individual results or errors. Weights and model configuration stay fixed until the cohort closes automatically after its final case. Leaving the context early cancels the worker and its child processes.

More

• Reason-CT with nodule tools: detect and segment nodules, then browse masks and measurements in a local CT viewer.
• MedGemma bridge: run MedGemma in a managed environment with local weights.
• This README describes the 0.4.7 release on PyPI. Unreleased changes are in the release notes; to use them, install from the locked source workspace described in the MCP guide.
• Development: declaring models, checkpoint conversion and the shared core runtime.

License

Apache-2.0. See third-party notices. Runtimes and model weights retain their own terms.