descriptron-mcp

The Descriptron programs as tools for Claude and any other MCP client.

MCP (Model Context Protocol) is an open standard that lets an AI assistant call software directly. With this server installed, you can ask Claude Desktop or Claude Code things like "summarise this COCO file, run the pipeline on it, and build the key", or "write the treatment for acok from the matrix and audit it", and it runs the same Descriptron programs you would run from a shell.

The server runs on your own computer and reads your own files. Nothing is uploaded anywhere except what the assistant itself reads through the tools.

Install

Python ≥ 3.10 is needed for the server itself. The programs can run in a different environment. See Configuration below.

Now. Install the analysis package from PyPI, then the server from GitHub (until the server is on PyPI too):

python -m venv descriptron-mcp-env
source descriptron-mcp-env/bin/activate        # Windows: descriptron-mcp-env\Scripts\activate

pip install descriptron-core
pip install "git+https://github.com/alexrvandam/Descriptron#subdirectory=packages/descriptron-mcp"

descriptron-mcp --check                        # shows what it found

For the GPU programs (detectors, SAM2-PAL, DINOLand) also pip install descriptron-vision.

Later (from PyPI):

pip install descriptron-mcp            # analysis programs (CPU)
pip install "descriptron-mcp[vision]"  # + detectors, SAM2-PAL, DINOLand (GPU)

With Docker instead (no Python setup; includes the GPU programs):

claude mcp add descriptron -- docker run -i --rm --gpus all \
  --user "$(id -u):$(id -g)" -v "$HOME:$HOME" \
  ghcr.io/alexrvandam/descriptron:2.0.3 mcp

Without an NVIDIA GPU (e.g. on a Mac), leave out --gpus all: Docker refuses to start with it, and everything except the GPU programs works the same. -v "$HOME:$HOME" makes your files appear inside the container at the same paths Claude uses; add another -v /path:/path for data elsewhere (e.g. an external drive). --user makes the files it writes yours rather than root's. Background jobs stop when the Claude session ends, because the container does.

Connect it

Claude Code

claude mcp add descriptron -- descriptron-mcp

Claude Desktop: in Settings → Developer → Edit config (claude_desktop_config.json):

{
  "mcpServers": {
    "descriptron": {
      "command": "descriptron-mcp",
      "env": { "DESCRIPTRON_MCP_WORKDIR": "/path/to/your/project" }
    }
  }
}

If descriptron-mcp is not on the PATH Claude Desktop sees, give the full path, e.g. /home/me/miniforge3/envs/descriptron/bin/descriptron-mcp.

Tools

Resource descriptron://workflow gives the recipe; prompt write_audited_treatment runs the write → audit → fix loop.

Writing and auditing are separate. When the assistant writes a treatment, it gets the numbers from species_evidence and then submits the text to audit_treatment. That audit is biorag_confabulation_checker_v2, which recomputes every value from the specimen matrix and checks each number against the structure it is printed next to. The writer never marks its own work.

Configuration (environment variables)

Example: run the server from a small Python 3.11 environment, but run the analysis in an existing conda environment and the GPU programs in another:

"env": {
  "DESCRIPTRON_CORE_PYTHON": "/opt/conda/envs/measure_env/bin/python",
  "DESCRIPTRON_VISION_PYTHON": "/opt/conda/envs/samm/bin/python"
}

What is not exposed

The annotation GUI. Annotation is interactive; the server works from the COCO files the GUI (or a detector) writes.

Licence

Apache-2.0. Part of Descriptron.