MedMLX

One Python API, command line and MCP server for native medical imaging on Apple Silicon. Run TotalSegmentator, nnU-Net, MedSAM2, SynthSeg and more through their independent MLX runtimes.

Models · Setup guide · MCP guide · Website

Apple Silicon · Metal · Python 3.13 · uv

Install

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

For a Python project, use uv add "medmlx[all,mcp]". Replace all with segment, generate or vision for a smaller install, and run uv tool upgrade medmlx to update MedMLX and its models. Model weights download on first use and keep their own terms.

Related MCP server: local-mcp

Quickstart

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

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

Save the run's arguments there as arguments.json. Relative paths resolve against --root:

{"image_path": "ct.nii.gz", "output_dir": "segment-ct"}

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

medmlx describe mlx-segment-ct
medmlx readiness mlx-segment-ct --arguments arguments.json --root ~/medmlx-work
medmlx run mlx-segment-ct --arguments arguments.json --root ~/medmlx-work

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. Run medmlx setup --all --progress to download every model's weights for offline use. See automatic weights and readiness.

Models

Model IDs are what medmlx run and medmlx describe take.

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:

Models without a declared peak, including nnunet-liver, nnunet-pancreas, nnunet-brats2021 and nnunet-autopet, 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",
)

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.