ai-mammogram-triage

At a glance: with high-resolution images, on patients the model never saw, it puts 87 % of BI-RADS 4-5 breasts in high_priority or review and only 6.5 % of normal (BI-RADS 1-2) breasts in high_priority (AUC 0.89). It runs on a CPU in 1–3 s per image, masks personal data before analysis and never stores images.

An MCP server for indicative triage of mammograms (CC/MLO views). It sorts each breast into three BI-RADS groups (1-2, 3 and 4-5) and gives it a priority level:

⚠️ Research tool. It is not a medical device, it is not clinically validated and it never replaces the radiologist's reading.

Why this project

My mother went through breast cancer. Seeing what she lived through taught me that, with this disease, acting in time is what saves lives. Yet many women do not have quick access to medical care: in parts of Latin America there is no radiologist nearby, and a mammogram can wait weeks before someone reads it.

This project is my attempt to help them. It lets a physician find out which mammograms look the most worrying, so those women reach a radiologist first and get care in time. — Alexander Valderrama

It is part of a three-repository project:

Related MCP server: MedVision MCP

What each analysis does

1. Masks personal data drawn over the image, using OCR. The text it reads is never returned or logged.

2. Checks that the image is a mammogram. It rejects ultrasound, MRI and unrelated photos, and warns about photo quality problems.

3. Classifies each view with two global models (512 and 1024 px). If the image is at least 1500 px high, it adds a 2048 px patch model (better with calcifications), a heatmap and up to 3 suspicious regions per view (where the patch model looks most; see docs/scores-and-levels.md).

4. Combines views of the same breast (for example RCC + RMLO) only when the client gives sides (R/L). There is no automatic side detection. Without sides, each view is evaluated as its own "breast", labelled "panel N". Then it applies the calibrated thresholds.

Images are never stored.

Summary language

All three tools accept language: "en" | "es" (default "en"). It sets the language of the human-readable text summary only, for example "HIGH PRIORITY", "REVIEW" or "NO SUSPICIOUS FINDINGS" in English. structuredContent is always in English.

Performance

Measured per breast on the half of the patients in the official VinDr-Mammo test split that was not used for calibration (half B):

Photos of screens or films perform worse than the original file. How these figures are computed and how to read them: docs/scores-and-levels.md.

Quick start

Requires Python 3.11. Two inference backends give the same results (see ADR 0005); install the one that matches your model bundle.

ONNX Runtime + RapidOCR (recommended, CPU only): no PyTorch. A full analysis peaks at ~0.6 GB of memory and takes 1–3 s per image on a 4-core CPU (~7 s for a 12 MP photo).

pip install -e ".[onnx,dev]"

PyTorch + EasyOCR (GPU or research): install PyTorch with CUDA first. A full analysis peaks at ~5 GB on CPU.

pip install torch==2.14.1 torchvision==0.29.1 --index-url https://download.pytorch.org/whl/cu126

pip install -e ".[torch,dev]"

The weights are not published (see ADR 0003). Set MAMMO_MODELS_DIR to the folder of the bundle exported by the training repository. The bundle's manifest.json declares its format (onnx or torch), and the server loads the matching backend.

Local, with Claude Desktop (stdio):

{
  "mcpServers": {
    "mammo-triage": {
      "command": "C:\\path\\to\\venv\\Scripts\\mammo-triage.exe",
      "args": ["stdio"],
      "env": { "MAMMO_MODELS_DIR": "C:\\path\\to\\bundle\\v1" }
    }
  }
}

Over HTTP (for the app or a tunnel): generate a key, put it in .env (copied from .env.example) and start the server.

mammo-triage new-key

mammo-triage http

The server listens on http://127.0.0.1:8765/mcp.

Pilot with doctors (Cloudflare HTTPS tunnels), in PowerShell:

.\scripts\start_pilot.ps1

If the server is installed in a virtual environment other than the default one, pass -Python. All parameters are listed in docs/operations.md.

Documentation

Tests

Regular tests, and integration tests with the real models (they need the bundle and a local image library):

pytest

pytest -m integration

Known limitations

• Trained mostly on Vietnamese mammograms (VinDr-Mammo). Performance on other populations and equipment is not validated.

• The filter accepts tomosynthesis slices as if they were 2D mammograms.

• Low-resolution photos use only the global model, with no heatmap.

• OCR may miss very faint or very large text.

Pilot access

The weights are not published, so the server cannot be run without the model bundle. Physicians and researchers who want to try it in a research pilot can request an access key with the pilot access form.

License

The code in this repository is licensed under the Apache License 2.0; see also NOTICE. It is provided "as is", without warranties of any kind. The model weights and the training code are not part of this repository and are not covered by this license.

Author

Alexander Valderrama · LinkedIn · @avalderrama