plantcv-mcp

plantcv-mcp

plantcv-mcp 是一个 MCP 服务，可让 AI Agent 使用 PlantCV 进行植物表型分析。它会返回性状数值及其测量所依据的分割叠加图；如果分割结果退化，则不会返回数值。

左图，channel="a", object_type="dark"：掩膜覆盖图像的 3.1%，包含 9 个连通区域，area=32427。右图，channel="s", object_type="dark"：掩膜覆盖 96.1%；它选中的是背景，area=1007829。

为什么要查看叠加图

两张图来自同一个文件，使用相同的阈值方法；唯一不同的是通道。没有图片时，两次运行都会返回 17 个单位正确、数值看似合理的性状。右图测量的其实是植物后方的墙面。红色标记被测量的像素；青色线条勾勒掩膜边缘。

因此，segment() 会返回叠加图和诊断信息，但不会返回性状；而 measure() 需要 segment() 生成的 session_id：在向你展示图像之前，不会测量任何单张图像。例外是 measure_images()，它可以对最多 200 张图像应用同一配方，且不生成叠加图。请先通过一张图像的叠加图确定配方（服务不会检查）；每张图像仍会通过 segment() 的保护检查，触发阻止性检查的图像不会返回性状。

使用 PlantCV 4.11.3 对合成渲染图（第一行： tests/fixtures/multi_specimen.png）和照片进行测量时，以下每种情况都会返回单位正确、数值看似合理的结果：

问题	不查看叠加图时得到的结果
四视角渲染图，使用全图 ROI	17 个合理的性状，描述四株合并后的植物
植物被图像边缘裁切	尺寸性状会被静默地作为下限返回
空掩膜	17 个零值性状，而 PlantCV 报告 in_bounds=True

安装

使用 uv 无需安装任何内容：uvx --python 3.13 plantcv-mcp 会获取并运行当前版本。否则：

pip install plantcv-mcp

需要 Python 3.11 到 3.13：PlantCV 4.11.3 需要低于 1.16 的 SciPy，而该版本没有适用于 Python 3.14 的 wheel，因此使用 --python 3.13 可避免 uvx 默认使用 3.14。PlantCV 及其科学计算依赖会让首次安装（或首次运行 uvx）耗时较长。在本地检出目录中：uv add /path/to/plantcv-mcp。一个可选工具 segment_leaves_sam() 需要 pip install "plantcv-mcp[sam]"（torch、torchvision、segment-anything）；未安装时，该工具会提示执行此命令后拒绝运行，其他工具均可正常使用。

配置 MCP 客户端

claude mcp add plantcv -- uvx --python 3.13 plantcv-mcp

Claude Desktop 和其他 stdio 主机：

{ "mcpServers": { "plantcv": { "command": "uvx", "args": ["--python", "3.13", "plantcv-mcp"] } } }

使用 pip 安装时，命令为 plantcv-mcp（查看配置）。 使用 list_methods() 验证。

标志：--root DIR（可重复指定，或使用 PLANTCV_MCP_ROOTS）会将所有读取操作以及服务保留的所有文件限制在你的图像目录内：plantcv-mcp --root /data/phenotyping。--no-isolate（或 PLANTCV_MCP_ISOLATE=0）会在进程内运行分析，而不是在具有崩溃隔离功能的工作进程中运行。

基准测试结果

我们将使用该服务的 Claude 与自行编写代码（主要使用 OpenCV）的 Claude 进行了比较。两者都运行在我们搭建的 Python 环境中，环境使用相同的 PlantCV 和 OpenCV；测试包含 46 个关于渲染植物图像的测量问题，每个问题运行 3 次。平局表示服务无需你搭建环境，就能达到相同结果。每次运行都答对的问题数量，服务与 Claude 自行编写的代码相比：Claude Haiku 5.5 为 38 对 32，Sonnet 5.5 为 33 对 28，Opus 5.5 为 42 对 44。差异均未达到显著水平（预注册；McNemar 精确检验 p 值分别为 0.15、0.23 和 0.63），且在这三个模型中，Claude 自行编写代码的成本都更低。

图表展示的是 2026-10-18 的 Opus 5.5 重跑结果，使用的是尚未发布的提交（051aff0），该提交增加了多通道分割规则和 zoom_image：使用自有代码时回答正确率为 97.1%，使用服务时为 95.7%。使用自有代码时，每个回答的成本为 $0.038，而使用服务时为 $0.066（中位数；区间没有重叠）。在 1.16.1 版本中，服务答对率为 86.2%，而自有代码为 95.7%（p = 0.18）。图像边缘清晰，因此无需模型的单色阈值分割也能答对 46 个问题中的 28 个。

这些问题由我们编写，基准测试也由我们执行；欢迎外部复测。方法、对照和限制： benchmarks/agent_qa； Haiku 和 Sonnet 的运行结果： 2026-10-20 重跑。

工具

工具	返回内容
suggest_segmentation	联系表，以及每种 object_type 会得到什么结果
segment	叠加图 + 诊断信息 + 警告，不含性状
refine	一个包含清理后掩膜的新会话，以及对应的叠加图
measure	性状；若掩膜退化则抛出错误
measure_images	在多张图像上应用同一配方；仅返回有效图像的性状
measure_regions	托盘中每株植物对应一行，以及编号叠加图
measure_morphology	叶片 / 茎的骨架性状 + 带编号的分割叠加图
count_leaves	通过分水岭估算叶片数量 + 带编号的叠加图
segment_leaves_sam	使用 Segment Anything 得到相同的计数（可选的 sam extra）
calibrate_scale_from_marker	根据已知实际尺寸的标记计算 px_per_mm
correct_lens_distortion	使用棋盘格校正鱼眼或广角图像的畸变
segment_hyperspectral、measure_spectral	根据指数阈值生成 HSI 会话；指数统计信息
segment_thermal、measure_thermal	根据 °C 波段生成热成像会话；掩膜下的 °C 统计信息
zoom_image	放大图像的一部分以便仔细查看（不是测量）
list_methods	通道、方法、对象类型、固定的 PlantCV 版本

典型流程：suggest_segmentation → segment → 查看叠加图 → 如果结果不正确，则使用其他通道、方法或极性再次运行 segment （如果结果接近正确，则使用 refine）→ measure。如果画面中有 ColorChecker，color_correct=true 会在分割前校正颜色，并将色卡排除在掩膜之外。每个工具的参数、示例响应及其测量依据： docs/GUIDE.md。

它会拒绝什么

每项保护措施都是针对某个具体故障添加的，并会指出下一步该怎么做。阻断性保护措施会拒绝提供数值；提示信息则会与数值一起返回。

• 掩膜反转（implausible_coverage）：上方右侧图像中的情况，17 个看似合理的性状描述的却是墙壁。
• 未选中任何内容，或 fill_size 删除了样本（empty_mask、fill_erased_mask）： PlantCV 返回 17 个零，且 in_bounds=True。
• 背景纹理（noisy_segmentation）：将生长室墙壁上的斑点作为一株植物进行测量。
• 一个掩膜中有多株植物（multi_specimen）：使用 measure_regions()。
• 比例尺错误、会话类型错误、分割后文件发生变化：拒绝处理，并指出正确的工具。
• 棋盘格无法确定的镜头校准，或请求使用色卡但未检测到色卡： 拒绝处理。

每项保护措施的存在原因，以及所有警告代码： docs/GUIDE.md#warnings-and-refusals。

安全性

如果未指定 --root，服务会读取主机用户有权读取的任何图像文件，并将其返回给模型。它只会写入经过镜头校正的图像、按需下载的 Segment Anything 检查点，以及高光谱和热成像输入的短期临时副本。请使用非 root 用户运行，并设置 --root。分析会在工作进程子进程中运行，因此原生崩溃会作为工具错误处理，不会导致服务停止。详情请见： docs/GUIDE.md#security-and-trust-boundary。

署名与许可证

采用 MIT 许可证。该项目依赖 PlantCV，其采用 Mozilla Public License 2.0。此处未随附或再分发任何 PlantCV 源代码；PlantCV 是普通的运行时依赖，因此 MIT 许可证适用于本项目自身的文件。本项目为非官方项目：与 Donald Danforth Plant Science Center 或 PlantCV 维护者无关联，未获其认可或赞助。请参阅 NOTICE。

请使用 CITATION.cff 引用本项目（归档于 doi:10.5281/zenodo.21713516）。变更记录： CHANGELOG.md。