{ "markdown": "# plantcv-mcp\n\n**Plant phenotyping over MCP — traits, plus the segmentation overlay they were measured from.**\n\n[![ci](https://github.com/musharna/plantcv-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/musharna/plantcv-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/plantcv-mcp)](https://pypi.org/project/plantcv-mcp/)\n[![python](https://img.shields.io/pypi/pyversions/plantcv-mcp)](https://pypi.org/project/plantcv-mcp/)\n[![license](https://img.shields.io/pypi/l/plantcv-mcp)](https://github.com/musharna/plantcv-mcp/blob/master/LICENSE)\n[![Glama](https://glama.ai/mcp/servers/musharna/plantcv-mcp/badges/score.svg)](https://glama.ai/mcp/servers/musharna/plantcv-mcp)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21713516.svg)](https://doi.org/10.5281/zenodo.21713516)\n\n\n\n[PlantCV](https://plantcv.org) as an MCP **measurement instrument**: it returns plant trait\nnumbers **and the picture they were computed from**, and refuses to return numbers when the\nsegmentation is degenerate.\n\n> Unofficial. Not affiliated with, endorsed by, or sponsored by the Donald\n> Danforth Plant Science Center or the PlantCV maintainers. See [NOTICE](https://github.com/musharna/plantcv-mcp/blob/master/NOTICE).\n\n## Why you are handed the overlay\n\nBoth images below come from the same file and the same threshold method — the only difference\nis one parameter.\n\n| ✅ `channel=\"a\", object_type=\"dark\"` | ❌ `channel=\"s\", object_type=\"dark\"` |\n| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ![correct segmentation](https://raw.githubusercontent.com/musharna/plantcv-mcp/master/docs/assets/overlay-correct.png) | ![inverted segmentation](https://raw.githubusercontent.com/musharna/plantcv-mcp/master/docs/assets/overlay-inverted.png) |\n| Mask covers **3.1%** of the frame, 9 components. `area=32427` | Mask covers **96.1%** — it is the **background**. `area=1007829` |\n\nThe failure on the right is what this server exists to prevent. Without the picture, both\nruns return seventeen traits with correct units and entirely believable magnitudes. The one\non the right is measuring the wall behind the plants.\n\nRed marks the pixels that were measured; a cyan line traces the mask's own boundary, drawn on\nthe mask's edge pixels so it never touches anything unmasked (the tint alone was invisible on\na photo of red beans).\n\n`segment()` returns the overlay and diagnostics but **no traits**. `measure()` requires the\n`session_id` that `segment()` mints. You cannot get a number without first being handed the\nimage it came from.\n\nThat is not a style preference. Measured on real images with PlantCV 4.11.3:\n\n| failure | what you get without the overlay |\n| --------------------------------- | ----------------------------------------------------------- |\n| four-view render, whole-image ROI | 17 plausible traits describing four merged plants |\n| plant clipped by the frame | size traits that are silently lower bounds |\n| empty mask | 17 traits of zeros, with PlantCV reporting `in_bounds=True` |\n\nAll three produce correctly-united, entirely believable numbers.\n\n## Install\n\nNo install is needed if the host has [uv](https://docs.astral.sh/uv/): `uvx plantcv-mcp`\nfetches the current release into its own environment and runs it. Otherwise:\n\n```bash\npip install plantcv-mcp\n```\n\nRequires Python 3.11+. Installing pulls PlantCV and its scientific stack, so the first\ninstall (or first `uvx` run) is not fast. From a checkout: `uv add /path/to/plantcv-mcp`.\n\n## Configure your MCP client\n\n```bash\nclaude mcp add plantcv -- uvx plantcv-mcp\n```\n\nClaude Desktop and other stdio hosts:\n\n```json\n{ \"mcpServers\": { \"plantcv\": { \"command\": \"uvx\", \"args\": [\"plantcv-mcp\"] } } }\n```\n\nWith a pip install, use `\"command\": \"plantcv-mcp\"` (and drop `uvx` from the `claude mcp add`\nline); from a checkout, `\"command\": \"uv\", \"args\": [\"run\", \"--directory\",\n\"/path/to/plantcv-mcp\", \"plantcv-mcp\"]`. Verify with `list_methods()`.\n\nFlags: `--root DIR` (repeatable, or `PLANTCV_MCP_ROOTS`) confines every read, and the one\nwrite, to your imagery: `plantcv-mcp --root /data/phenotyping`. `--no-isolate` (or\n`PLANTCV_MCP_ISOLATE=0`) runs analyses in-process instead of in the crash-containing worker.\n\n## Tools\n\n| tool | returns |\n| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `suggest_segmentation(image_path, channel, method)` | contact sheets, and what each `object_type` would yield |\n| `segment(image_path, channel, method, ...)` | overlay + diagnostics + warnings — **no traits** |\n| `refine(session_id, ops)` | a NEW session with a cleaned-up mask, plus its overlay |\n| `measure(session_id, analyses, px_per_mm, ...)` | traits, or a raised error on a degenerate mask |\n| `calibrate_scale_from_marker(image_path, x, y, w, h, marker_length_mm)` | `px_per_mm` from a marker of known real size |\n| `correct_lens_distortion(image_path, checkerboard_dir, ...)` | a fisheye/wide-angle image undistorted via checkerboard calibration, written next to the input or to `output_path` |\n| `measure_regions(session_id, nrows, ncols, ...)` | one row per plant in a tray (RGB traits, thermal temperatures or HSI index stats), plus the numbered overlay |\n| `measure_morphology(session_id, prune_size, tangent_size, ...)` | leaf/stem skeleton traits + the numbered-segment overlay |\n| `measure_images(image_paths, channel, method, ...)` | one recipe across many images (per plant with a grid); traits only where valid; time-budgeted |\n| `segment_hyperspectral(envi_path, index, threshold, ...)` | an HSI session from a spectral-index threshold + pseudo-RGB overlay |\n| `measure_spectral(session_id, indices, ...)` | index statistics (and, opt-in, per-band reflectance) |\n| `segment_thermal(path, min_c, max_c, ...)` | a thermal session from a °C band + grey-frame overlay |\n| `measure_thermal(session_id, ...)` | max/min/mean/median °C under the mask |\n| `list_methods()` | channels, methods, object types, pinned PlantCV version |\n\nTypical loop: `suggest_segmentation` → `segment` → **look at the overlay** → `segment` again\nwith a different channel, method or polarity if it is wrong (or `refine` if it is nearly\nright) → `measure`. Pass `color_correct=true` to `segment` when a ColorChecker is in the\nframe: colours are corrected to the reference before segmenting and measuring, and the card\nitself is excluded from the mask (`exclude_color_card=true` does only the exclusion).\n\nThe call that produced the left-hand image above:\n\n```json\n{\n \"image_path\": \"multi_specimen.png\",\n \"channel\": \"a\",\n \"method\": \"otsu\",\n \"object_type\": \"dark\"\n}\n```\n\nIts response — verbatim, apart from a shortened `session_id` and an elided message — with\nthe overlay arriving beside it as an image:\n\n```json\n{\n \"session_id\": \"9d2384c8-…\",\n \"channel\": \"a\",\n \"method\": \"otsu\",\n \"object_type\": \"dark\",\n \"fill_size\": 200,\n \"color_correct\": false,\n \"mask_fraction\": 0.031,\n \"component_count\": 9,\n \"major_object_count\": 4,\n \"largest_area\": 8628,\n \"overlay_scale\": 1.0,\n \"overlay_png_bytes\": 748233,\n \"warnings\": [\n {\n \"code\": \"multi_specimen\",\n \"message\": \"4 comparably-sized objects detected (areas: [8628, 7981, 7106, 6748]). …\"\n }\n ]\n}\n```\n\n## What it refuses, and why\n\nEvery guard was calibrated against a real failure and names the next action. Blocking\nguards withhold numbers; advisories travel with them.\n\n- **Inverted mask** (`implausible_coverage`) — the right-hand image above: 96% of the frame\n selected, seventeen believable traits, all describing the wall.\n- **Nothing selected, or `fill_size` deleted the specimen** (`empty_mask`,\n `fill_erased_mask`) — PlantCV returns seventeen zeros with `in_bounds=True`.\n- **Background texture** (`noisy_segmentation`) — a sorghum photo measured as one\n 650,000-px plant made of 118 chamber-wall specks.\n- **Several plants in one mask** (`multi_specimen`) — the number describes the group; use\n `measure_regions()`, which measures each plant and numbers the overlay.\n- **Wrong scale, wrong kind, changed file** — a marker measured 4.35× wrong by PlantCV's own\n ROI method; a thermal session handed to an RGB measurer; an image edited after\n segmentation. Each is refused naming the right tool.\n- **A lens calibration the boards do not determine** — a set whose focal length the fit\n leaves undetermined is refused naming the number, and one that determines it only loosely\n is accepted with the looseness said. That judgement is made per view, because the fit's\n uncertainty falls as frames are added whether or not the geometry improves: re-saving the\n same photographs, or shooting more of the same angle, buys nothing. A frame that fits far\n worse than the rest, or that moves the answer far more than the others allow, is dropped\n by name and the camera refitted.\n- **No colour card when one was asked for** — `color_correct=true` raises rather than\n returning colour traits that look corrected and are not.\n\nEvery warning code, every tool's parameters, and the measured facts behind each guard:\n**[docs/GUIDE.md](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md)** — [segmenting](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#segmenting) · [traits and units](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#what-it-measures) ·\n[real-world units](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#real-world-units) · [lens correction](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#correcting-lens-distortion) ·\n[polarity](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#getting-the-polarity-right) · [refining](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#refining-a-mask) ·\n[colour correction](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#colour-correction) ·\n[trays](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#measuring-a-tray) · [morphology](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#morphology-leaves-stem-branch-points) ·\n[batches](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#measuring-many-images) · [hyperspectral and thermal](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#hyperspectral-and-thermal) ·\n[warning reference](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#warnings-and-refusals).\n\n## Security\n\nThis server reads image files the host user can read and returns them to the model as\nimages; with no `--root` there is no allow-list. It writes exactly one thing: the corrected\nimage from `correct_lens_distortion`, next to its input (replacing an earlier run's output\nof the same name) or at an `output_path` that must not exist yet — under the same roots,\nnever through a symlink. Run it as a user whose read\naccess you are comfortable exposing, set `--root`, and do not run it as root. PlantCV/OpenCV\nanalyses run in a worker subprocess, so a native crash is a tool error, not a dead server.\nDetails:\n[security](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#security-and-trust-boundary) · [read roots](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#restricting-what-the-server-may-read) ·\n[crash containment](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#crash-containment-the-analysis-worker) · [limitations](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md#limitations).\n\n## Attribution and licensing\n\nThis project is MIT licensed. It depends on\n[PlantCV](https://github.com/danforthcenter/plantcv), which is licensed under the\n**Mozilla Public License 2.0**. No PlantCV source is vendored or redistributed\nhere — it is an ordinary runtime dependency — so the MIT license applies to this\nproject's own files. See [NOTICE](https://github.com/musharna/plantcv-mcp/blob/master/NOTICE) for the full statement.\n\n## More\n\n- [docs/GUIDE.md](https://github.com/musharna/plantcv-mcp/blob/master/docs/GUIDE.md) — the full guide\n- [CHANGELOG.md](https://github.com/musharna/plantcv-mcp/blob/master/CHANGELOG.md) — what changed, and why\n- [docs/MUTATION-CHECKS.md](https://github.com/musharna/plantcv-mcp/blob/master/docs/MUTATION-CHECKS.md) — every guard disabled on purpose, and\n the test that went red for it\n- Citing it: [CITATION.cff](https://github.com/musharna/plantcv-mcp/blob/master/CITATION.cff)\n (archived at [doi:10.5281/zenodo.21713516](https://doi.org/10.5281/zenodo.21713516))\n\nImages on this page are rendered from `tests/fixtures/multi_specimen.png`, an original render\nby the author, and regenerate from committed code.\n", "bytes": 14560, "sha": "58e6a82d6482837ead4f83a1c220cc412b328a4585b124679a8d945c2647e7a6", "repo_slug": "musharna/plantcv-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_musharna_plantcv_mcp_6e58fd77/readme" }