vmd-hydrate-mcp

vmd-hydrate-mcp

任意の LLM から VMD を操作 — Model Context Protocol を通じて GROMACS/LAMMPS のトラジェクトリをレンダリングし、クラスレートハイドレートケージを解析します。

クイックスタート · 機能 · MCP ツール · 使い方 · 한국어

---

メモ

Claude（または任意の MCP クライアント）から VMD を直接操作できる MCP サーバーです。GROMACS/LAMMPS のトラジェクトリを読み込み、クラスレートハイドレートケージを特定（sI/sII/sH）し、ヘッドレスレンダリングのスクリプトを実行して、秩序パラメーター（F3/F4）と水素結合ネットワークを計算することで、分子動力学解析を対話形式で行えるようにします。既存の VMD MCP とは異なり、状態を保持する VMD セッションを維持し、デフォルトで安全であり、他の MCP にはない機能である ハイドレートケージ科学を提供します。

動作例

すべてのフレームは、MCP サーバー経由で完全に操作される実際のヘッドレス VMD（Tachyon）レンダリングです。sII ケージ — 128 × 5¹² + 60 × 5¹²6⁴ — はモックではなく、このリポジトリが特定したものです。 · ▶ 高画質 MP4

機能

• クラスレートケージの特定 -- 水素結合ネットワークからハイドレートケージ（5¹²、5¹²6²、5¹²6⁴、…）を検出・分類し、結晶構造（sI/sII/sH）にラベルを付けます。sII ベンチマーク（小ケージ 128 個、完全一致）で検証済みです。
• 写実的なプロンプト指定ケージレンダリング -- アンビエントオクルージョンとシャドウを適用してケージをレンダリングします。デフォルトは正投影で、ケージの種類ごとに統一色を 1 色使用します（厳選したパレット：5¹²＝シアン、5¹²6⁴＝赤、…）。「sII の大ケージだけをマゼンタで、幅を強調して表示して」と頼むだけで、MCP が対象を絞り込み、色を変更し、太く表示します。
• 状態を保持する VMD セッション -- 永続的な VMD プロセス（Tcl ソケットサーバー）が分子、選択、カメラの状態をツール呼び出し間で保持するため、コマンドごとに再読み込みする必要はありません。
• ハイドレート秩序パラメーター -- F3（四面体性）と F4（⟨cos 3φ⟩）を NumPy のみで計算し、参照値と小数点以下 6 桁まで一致することを検証済みです（sII ベンチマークで F4 = 0.926698）。
• 水素結合ネットワーク -- ケージ特定の基盤となる、水分子間の水素結合グラフと配位統計を提供します。
• ヘッドレスレンダリング -- ディスプレイや GPU を使わず、CPU の Tachyon でレイトレーシングした PNG を生成し、画像としてインラインで返します。ラップトップ、サーバー、HPC で動作します。
• GUI モード -- 完全なオフスクリーン実行（デフォルト）、または VMD_HYDRATE_MCP_DISPLAY=gui を設定して表示可能な VMD ウィンドウを開き、Claude がシステムを読み込み、色付け、回転、レンダリングする様子をリアルタイムで確認できます。
• GROMACS + LAMMPS -- 1 つのサーバーで .gro/.xtc/.trr、LAMMPS の .data/dump、PDB、DCD、mmCIF を読み込みます。
• デフォルトで安全 -- ファイルシステムの許可リスト、Tcl コマンドの許可リスト（回避可能な拒否リストではありません）、ループバック接続かつトークン認証付きの制御ソケットを備えています。危険な run_tcl は公開していません。
• MCP ネイティブ -- 明確な英語のツール名と型付き出力を備え、Claude Desktop、Claude Code、任意の MCP クライアントで動作します。

クイックスタート

重要

ローカルへの VMD のインストールが必要です（2.0b1 または 1.9.4+）。このサーバーはお使いの VMD を操作します。レジストリにもパッケージにも VMD は含まれていません。macOS では VMD は .app 内にあるため、vmd が PATH にない場合は VMD_BIN を設定してください。（純粋なハイドレート／測定ツールは VMD がなくても動作します。）

インストール

uvx でインストール不要（推奨）：

uvx vmd-hydrate-mcp                                  # run the server
uvx --from 'vmd-hydrate-mcp[mda]' vmd-hydrate-mcp    # + MDAnalysis for measures/selection

ソースからインストール：

git clone https://github.com/wjgoarxiv/vmd-hydrate-mcp.git
cd vmd-hydrate-mcp && uv pip install -e ".[mda]"

MCP クライアントに登録する

Claude Code — コマンド 1 つで設定できます：

claude mcp add vmd-hydrate -- uvx vmd-hydrate-mcp

Claude Desktop／その他のクライアント — mcpServers 設定に追加します（またはプロジェクトの .mcp.json にコミットします）：

{
  "mcpServers": {
    "vmd-hydrate": {
      "command": "uvx",
      "args": ["vmd-hydrate-mcp"],
      "env": { "VMD_HYDRATE_MCP_ALLOW_DIR": "/path/to/your/data" }
    }
  }
}

重要

VMD_HYDRATE_MCP_ALLOW_DIR（OS のパス区切り文字で区切る）に、サーバーによる読み取りを許可するディレクトリを設定してください。すべてのファイル引数はこの許可リストに対して実パスを検証し、リスト外のパスは拒否されます。

GUI モードでの操作

デフォルトでは、サーバーは VMD をヘッドレス（オフスクリーン）で操作します。代わりに、Claude がリアルタイムで操作する様子を実際の VMD ウィンドウで確認するには、サーバーの環境変数に VMD_HYDRATE_MCP_DISPLAY=gui を追加します：

{ "mcpServers": { "vmd-hydrate": {
  "command": "uvx", "args": ["vmd-hydrate-mcp"],
  "env": { "VMD_HYDRATE_MCP_DISPLAY": "gui", "VMD_HYDRATE_MCP_ALLOW_DIR": "/path/to/data" }
}}}

その後、*「prod.gro を読み込み、水を点表示、界面活性剤を VDW 表示にして、ゆっくり回転させて」*のように依頼できます。ウィンドウは load_structure → add_representation → rotate_view を通じてリアルタイムに更新されます。（ローカルのデスクトップセッションが必要です。同じ Tcl ソケットが両方のモードを操作します。）

MCP ツール

ツール	目的	バックエンド
vmd_status	VMD のバージョンと、ライブセッションで読み込まれた分子	VMD
load_structure	構造／軌跡を読み込む（molid を返します）	VMD
list_molecules	読み込み済みの分子を一覧表示する	VMD
set_representation	分子のスタイル／色／マテリアル／選択（表現を置き換えます）	VMD
add_representation	別の表現を重ねる（複数表現の表示）	VMD
clear_representations	すべての表現を削除する	VMD
rotate_view / zoom_view / reset_view	ライブカメラ操作（GUI モードで表示されます）	VMD
render	現在の表示をヘッドレスで PNG にレンダリングする	VMD + Tachyon
resolve_selection	選択範囲内の原子数（.gro の原子数が 0 になる問題を検出します）	MDAnalysis
measure_geometry	原子インデックスによる距離／角度／二面角	MDAnalysis
radius_of_gyration	選択範囲の Rg	MDAnalysis
hydrate_order_params	水の F3 + F4 秩序パラメーター	NumPy
hbond_network	水素結合ネットワークと水の配位数	NumPy
identify_cages	ケージ数（5¹²／5¹²6⁴／…）と sI／sII／sH 構造	NumPy
render_cages	フォトリアリスティックなケージのレンダリング（AO + 影、正投影）。プロンプトでケージをフィルタリング／再着色／強調できます	VMD + NumPy

使用方法

1. 軌跡フレームのハイドレート秩序を解析する

Compute the F3/F4 order parameters for hydrate.gro

f4_overall、f3_overall、水の数、および平易な言葉による解釈（結晶性／ハイドレート様／液体／氷）を返します。

2. 構造をレンダリングする

Load hydrate.gro, show the water oxygens as VDW spheres, and render it

CPU Tachyon を使用してヘッドレスでレンダリングした PNG をインラインで出力します。

3. 水素結合ネットワークを調べる

Build the water hydrogen-bond network for hydrate.gro at frame 0

結合数と平均配位数（よく形成されたクラスレートでは約 4）を返します。

4. プロンプトでハイドレートケージのスタイルを指定する

Load hydrate.gro and show only the sII large cages in magenta with emphasized width

マゼンタ色でエッジを太くした 5¹²6⁴ ケージのみを、フォトリアリスティックな正投影画像としてレンダリングします。MCP はこれを render_cages(cage_types=["51264"], highlight_color="magenta", emphasis=True) に変換します。フィルターを省略すると、すべてのケージタイプがそれぞれのパレット色（5¹² はシアン、5¹²6⁴ は赤、…）で描画されます。

実際に VMD を操作しますか？

はい。コマンドを 1 つ実行するだけで確認できます。examples/verify.py は、同梱の sII CO₂ ハイドレートの例で、MCP サーバーが公開するものと同じコードを実行します。実際の VMD バイナリに ping を送信し、ケージを特定して、ヘッドレスでレンダリングします。

python examples/verify.py

出力例：

[1] VMD found : /Applications/VMD2b1.app/.../vmd_MACOSXARM64
    ping      : pong 2.0b1 MACOSXARM64
[2] Identifying cages in a real sII CO2 hydrate (1088 waters)...
    cage counts : {'51264': 60, '512': 128}
    structure   : sII  (confidence 0.93)
    F4 order    : 0.965  (highly ordered (crystalline hydrate / ice-like))
[3] Rendering cages headlessly (blue = 5^12, red = 5^12 6^4)...
    saved       : examples/output/cages.png (362495 bytes)
OK — vmd-hydrate-mcp drove VMD and identified the cages above.

以下の画像は、このパイプラインで生成した実際の未加工の VMD レンダリング画像です（イラストではありません）。

sII 結晶 — 種類ごとに色分けされたケージ（シアン 5¹²、赤 5¹²6⁴）、フォトリアリスティックな Tachyon

単一の 5¹² 十二面体、PBC をまたいで展開（アンビエントオクルージョン＋シャドウ）

冒頭のデモ動画は、このようなフレームを組み合わせて作成しています。VMD を操作する video/build_frames.py と、Remotion で合成する video/remotion/ をご覧ください。python video/build_frames.py && cd video/remotion && npm i && npm run gif で再作成できます。

仕組み

  [.gro / .xtc / LAMMPS dump]
            |
            v
     MCP client (Claude)  --stdio-->  vmd-hydrate-mcp (FastMCP)
                                          |            |
                          numbers  <------+            +------>  visualization
                     MDAnalysis + NumPy                     persistent VMD session
                   (F3/F4, H-bonds, Rg)                    (Tcl socket, 127.0.0.1)
                          |                                         |
                          v                                         v
                  structured JSON                         Tachyon --> PNG image

数値を扱う科学計算は Python で実行します（ディスプレイ不要で、CI で単体テスト可能です）。可視化とレンダリングは、トークンで保護された長時間稼働の VMD プロセスで実行します。両者で単位が混在することはありません。ハイドレートの計算ではナノメートルを、VMD／MDAnalysis の測定では Ångström を使用します。

要件

依存関係	必須	用途
VMD 2.0b1 または 1.9.4+	可視化／レンダリングに必要	可視化エンジン
Python 3.10+	はい	サーバー
mcp	はい	Model Context Protocol SDK
MDAnalysis（[mda]）	測定／選択に必要	トポロジーを考慮した読み込み
sips／ImageMagick／Pillow	レンダリングに必要	TGA→PNG 変換

警告

macOS では、VMD は .app として提供され、CLI バイナリはバンドル内にあります。vmd が PATH にない場合は、VMD_BIN にバイナリを設定してください（例：/Applications/VMD*.app/Contents/vmd*/vmd_MACOSXARM64）。純粋なハイドレート／測定ツールは VMD なしで動作します。

コントリビューション

1. フォークしてブランチを作成します（git checkout -b feature/x）。
2. uv pip install -e ".[dev,mda]" を実行し、pytest が成功する状態を保ってください（科学計算のテストに VMD は不要です）。
3. コミットしてプッシュし、PR を作成してください。バグを見つけた場合は、issue を作成してください。

ライセンス

MIT — LICENSE をご覧ください。