plantcv-mcp

plantcv-mcp

plantcv-mcp は、AI エージェントが PlantCV による植物の表現型解析を実行できる MCP サーバーです。特性の数値と、その測定元となるセグメンテーションオーバーレイを返します。また、セグメンテーションが不適切な場合は数値を返しません。

左、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枚の画像に1つのレシピを適用し、オーバーレイは生成しません。まず1枚の画像のオーバーレイでレシピを確定してください（サーバー側では確認しません）。どの画像も引き続き segment() のガードを通過し、ブロック対象のガードに引っかかった画像からは特性が返されません。

PlantCV 4.11.3を使い、合成画像（1行目： tests/fixtures/multi_specimen.png）と写真で測定した場合、次のそれぞれで単位が正しく、妥当な数値が返されます。

失敗	オーバーレイがない場合に得られるもの
4方向から見た画像、画像全体をROIに指定	4つの植物が結合した状態を示す、妥当に見える17個の特性
フレームで植物が切れている	下限値であることが通知されないサイズ特性
空のマスク	すべて0の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にはSciPy 1.16未満が必要ですが、このバージョンにはPython 3.14用のホイールがないため、--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 を比較しました。比較には、同じ PlantCV と OpenCV を設定した Python 環境を使い、レンダリングされた植物画像に関する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）。また、3モデルすべてで Claude の自前コードのほうが低コストでした。

このグラフは、2026-10-18に未公開コミット（051aff0）を使って再実行した Opus 5.5 の結果です。このコミットでは、複数チャンネルのセグメンテーションルールと 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	複数画像に対する1つのレシピ。有効な場合のみ形質を返します
measure_regions	トレイ内の植物ごとに1行と、番号付きオーバーレイ
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 は in_bounds=True とともに17個のゼロを返します。
• 背景のテクスチャ（noisy_segmentation）：チャンバーの壁の斑点が1つの植物として測定されます。
• 1つのマスクに複数の植物がある（multi_specimen）：measure_regions() を使用してください。
• スケールが間違っている、セッションの種類が間違っている、セグメント化後にファイルが変更された：適切なツールを示して拒否されます。
• ボードでは決定できないレンズ校正、または要求されたのにカラーカードがない：拒否されます。

各ガードが存在する理由と、すべての警告コードについては、こちらを参照してください： docs/GUIDE.md#warnings-and-refusals。

セキュリティ

--root を指定しない場合、サーバーはホストユーザーが読み取り可能なあらゆる画像ファイルを読み込み、モデルに返します。書き込むのは、レンズ補正済みの画像、ダウンロードを要求された場合の Segment Anything のチェックポイント、およびハイパースペクトル画像と熱画像の入力の短期間だけ保存される一時コピーのみです。--root を設定し、root 以外のユーザーとして実行してください。解析はワーカープロセスで実行されるため、ネイティブクラッシュが発生してもツールのエラーとなり、サーバーが停止することはありません。詳細： docs/GUIDE.md#security-and-trust-boundary。

帰属とライセンス

MIT ライセンスです。PlantCV に依存しており、PlantCV は Mozilla Public License 2.0 でライセンスされています。PlantCV のソースはここに同梱も再配布もされていません。通常のランタイム依存関係であるため、MIT ライセンスはこのプロジェクト独自のファイルに適用されます。非公式のプロジェクトであり、Donald Danforth Plant Science Center または PlantCV のメンテナーとは提携しておらず、承認や後援も受けていません。NOTICE をご覧ください。

CITATION.cff を引用してください（doi:10.5281/zenodo.21713516 にアーカイブされています）。変更内容： CHANGELOG.md。