MedMLX home AI-IR lab Get started

Command line

The medmlx command finds, checks and runs models, downloads their weights and starts the MCP server.

From the medmlx 0.4.2 documentation. README · Setup guide

Install

This installs the medmlx command and the MCP server with every model family. You need macOS 14.0 or later on Apple Silicon and uv.

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

For a smaller install, replace all with segment, generate or vision. Weights download the first time you run a model, and each set keeps its own license.

Run a model

Run a model 
medmlx describe mlx-segment-ct
medmlx readiness mlx-segment-ct --arguments arguments.json --root /path/to/work
medmlx run mlx-segment-ct --arguments arguments.json --root /path/to/work

describe lists the arguments a model takes. readiness checks that the model can run on this Mac, without downloading anything. run reads the arguments from a JSON file, runs the model and waits for it to finish. Relative paths in the file are read from the --root folder.

Most models download their weights the first time they run, so you can leave out weights_path. Later runs reuse that download, and each run records which weights it used. To use your own weights, pass a local folder as weights_path. MedGemma and MRSegmentator need local weights for now.

Commands

  • medmlx models--task, --family

    Lists the installed models.

  • medmlx describeMODEL_ID

    Shows the arguments a model takes and how to use them.

  • medmlx readinessMODEL_ID…, --arguments, --root

    Checks that a model can run on this Mac, without downloading anything.

  • medmlx runMODEL_ID, --arguments, --root

    Runs a model and waits for it to finish.

  • medmlx setupMODEL_ID, --all, --refresh, --plan, --progress

    Downloads weights ahead of time, for working offline.

  • medmlx serve--root

    Starts the MCP server for an agent. Needs the mcp extra.

  • medmlx checkpoints--model-id

    Lists where model checkpoints come from. Downloads nothing.

  • medmlx packagesNo arguments

    Lists the model families and which runtimes are installed.

  • medmlx runtimeNo arguments

    Checks MLX and Metal on this Mac.

Every command except serve prints JSON. If an installed model fails to load, models lists it under discovery_errors and exits with an error.

Weights

Models download their weights the first time they run. To work offline, download them first. The first command downloads every installed model, and the second downloads one:

Download weights 
medmlx setup --all --progress
medmlx setup mlx-segment-ct --progress

If one model fails, the rest still download, and the command exits with an error at the end. Models that need manual setup are reported as unsupported. Downloading doesn't run or test a model.

To see what would download without downloading anything, run medmlx setup --all --plan. On its own, medmlx setup lists the installed models and where their weights come from. To update or repair a download, run medmlx setup MODEL_ID --refresh. Folders you pass as weights_path are never changed.

Weights are saved as plain files in ~/.cache/medmlx/<model_id>. Set MEDMLX_ASSET_CACHE to use another folder. Finished downloads work offline, and an interrupted download picks up where it left off.

MCP server

MCP server 
medmlx serve --root /path/to/work

Give this command to your MCP client as the server to start. When the client disconnects, its running jobs stop. The MCP guide shows how to connect a client and run a model step by step.