vmd-mcp: Claude MCPを介したVMD2の自然言語制御

著者: Omar Arias-Gaguancela, PhD 所属: SciLearningWorkshops LLC

vmd-mcpとは？

vmd-mcpは、Model Context Protocol (MCP)サーバーであり、ClaudeにVMD2 (Visual Molecular Dynamics) を直接プログラムで制御する機能を提供します。Tclスクリプトを書いたりVMDのGUIを操作したりする代わりに、自然な英語でやりたいことを説明するだけで、Claudeが構造の読み込み、表示設定、距離測定、RMSD計算、画像レンダリングなどを実行します。

計算生物学者にとっての重要性

分子動力学解析はボトルネックとなっています。シミュレーションの生成は自動化が進んでいますが、その解釈には依然としてTclスクリプト、VMDのGUI、コマンドラインツールに関する専門知識が必要です。vmd-mcpはこのギャップを埋めます。

このツールを使えば、研究者は1回の会話で軌跡ファイルから出版品質の図や定量的な測定結果を得ることができ、Tclの知識は不要です。また、分野に参入する研修生や学生の障壁を下げ、ソフトウェアの構文ではなく生物学に集中できるようにします。セキュリティを意識した設計（パスの許可リスト、Tclコマンドの検証）により、共有環境や教育用コンピューティング環境でも安全に導入できます。

主な機能

• 23個のMCPツール: 構造の読み込み、軌跡ナビゲーション、表示設定、測定、レンダリング、Tclパススルーを網羅

• 自然言語インターフェース: タンパク質の可視化、距離の測定、RMSDの計算などを自然な英語でClaudeに依頼可能

• サブプロセスモード: Windows上でVMD2をヘッドレスで起動・制御し、手動のTclスクリプトは不要

• セキュリティ第一の設計: すべてのファイルパスは設定可能な許可リストに対して検証されます。Tclコマンドは危険な操作（exec, open, file, socketなど）をブロックするためにサニタイズされます

• Windowsネイティブ: CREATE_NO_WINDOWサブプロセス修正を含み、操作中に不要なコンソールウィンドウが表示されません

• ソケットモード: localhost:5555で実行中のVMDインスタンスに接続可能

• モックVMDサーバー: mock_vmd.pyを使用してVMDをインストールせずにパイプライン全体をテスト可能

• MCPリソース: Claudeはコマンドを発行する前にライブのVMD状態（vmd://status, vmd://molecules, vmd://selections-guide）を照会可能

要件

インストール

1. リポジトリのクローン

git clone https://github.com/oarias/vmd-mcp.git
cd vmd-mcp

2. 仮想環境の作成 (推奨)

python -m venv .venv
.venv\Scripts\Activate.ps1

3. 依存関係のインストール

pip install -r requirements.txt

4. VMD2のインストール確認

サーバーは以下の場所にVMD2があることを想定しています:

C:\Program Files\University of Illinois\VMD2\vmd.exe

インストールパスが異なる場合は、vmd_mcp_config.jsonを開いてvmd_executableを更新してください:

{
  "vmd_executable": "C:\\Program Files\\University of Illinois\\VMD2\\vmd.exe",
  "communication_mode": "subprocess",
  "socket_host": "localhost",
  "socket_port": 5555,
  "socket_timeout": 10.0,
  "subprocess_args": ["-dispdev", "win"],
  "allowed_directories": [
    "C:\\Users\\YourName\\Desktop",
    "C:\\Users\\YourName\\Documents",
    "C:\\Users\\YourName\\Downloads"
  ]
}

セキュリティ上の注意: allowed_directories内のファイルのみがVMDに読み込めます。必要なデータディレクトリを追加してください。

Claude Codeへのvmd-mcpの登録

オプションA: Claude Code CLI

claude mcp add vmd-mcp `
  --command "C:\Users\YourName\Desktop\vmd-mcp\.venv\Scripts\python.exe" `
  --args "C:\Users\YourName\Desktop\vmd-mcp\vmd_mcp_server.py"

オプションB: 手動設定

%APPDATA%\Claude\claude_desktop_config.json (デスクトップアプリ) または .claude.json (CLI) を編集します:

{
  "mcpServers": {
    "vmd-mcp": {
      "command": "C:\\Users\\YourName\\Desktop\\vmd-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourName\\Desktop\\vmd-mcp\\vmd_mcp_server.py"],
      "cwd": "C:\\Users\\YourName\\Desktop\\vmd-mcp"
    }
  }
}

保存後にClaude Codeを再起動してください。接続されたMCPサーバーの下にvmd-mcpが表示されるはずです。

接続の確認

Claudeにこう尋ねてください: "What MCP tools are available for VMD?" サーバーが正しく接続されていれば、Claudeが23個のツールすべてを列挙します。

使用例: 自然言語プロンプト

構造と軌跡の読み込み

Load C:\Users\me\Desktop\project\protein.pdb into VMD.

Load MtFAAH_1MAG16.pdb as the topology and MtFAAH_1MAG16_10ns_merged.dcd
as the trajectory.

可視化

Show the protein as NewCartoon colored by secondary structure,
and display the ligand as Licorice with CPK coloring.

Set the background to white and reset the camera.

Add a VDW surface for all water molecules within 5 Å of the active site.

軌跡ナビゲーション

How many frames are in molecule 0?

Go to frame 500 and take a snapshot — save it to C:\Users\me\Desktop\frame500.tga.

Play the trajectory from frame 0 to 1000 at speed 5.

測定

Measure the distance between atom 1042 and atom 2318 in the current frame.

What is the angle formed by atoms 101, 205, and 310?

Compute the backbone RMSD relative to frame 0 across all frames.

原子情報

What residue and atom name is atom index 4711?

List all atoms in the selection "resname MAG" — show residue IDs and atom names.

レンダリングと保存

Render a high-quality Tachyon image to C:\Users\me\Desktop\figure1.tga.

Save the current VMD session to C:\Users\me\Desktop\session.vmd.

クイックリファレンス: すべてのツール

VMD原子選択クイックリファレンス

protein                        all protein atoms
backbone                       N, CA, C, O atoms
resname LIG                    residue named LIG
resid 45                       residue number 45
resid 45 to 102                residue range
chain A                        chain A
name CA                        alpha carbons only
within 5 of resname LIG        atoms within 5 Å of ligand
protein and not water          protein excluding solvent

トラブルシューティング

VMDが起動しない

原因: vmd_mcp_config.jsonのvmd_executableパスが正しくありません。 解決策: VMDを直接実行してパスを確認してください:

& "C:\Program Files\University of Illinois\VMD2\vmd.exe" -dispdev none -e nul

VMDがエラーなしで終了すれば、パスは有効です。必要に応じて設定のvmd_executableを更新してください。

コマンドごとにコンソールウィンドウが点滅する

原因: CREATE_NO_WINDOWサブプロセスフラグが欠落しています。 解決策: これはvmd_controller.pyですでに処理されています:

if hasattr(subprocess, "CREATE_NO_WINDOW"):
    kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW

それでもウィンドウが点滅する場合は、Python 3.7+を実行しており、このブロックを変更していないことを確認してください。このフラグは、Windowsがサブプロセスの子に対してデフォルトで作成する隠しコンソールを抑制します。

Windowsでのasyncioイベントループエラー (ProactorEventLoop)

原因: Windows上のPython 3.8+はデフォルトでProactorEventLoopを使用しますが、これはMCP SDKが使用する特定のサブプロセスパイプ操作と競合します。 解決策: 以下のポリシーはvmd_mcp_server.pyの起動時にすでに設定されています:

import asyncio, sys
if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

サーバーを変更した後にこのエラーが発生した場合は、asyncio.run()の前にこのポリシーが設定されていることを確認してください。

Path outside allowed directories エラー

原因: 読み込もうとしているファイルがallowed_directoriesに含まれていません。 解決策: vmd_mcp_config.jsonにディレクトリを追加してください:

"allowed_directories": [
  "C:\\Users\\YourName\\Desktop",
  "C:\\Users\\YourName\\Projects\\my_md_data"
]

Claude CodeにMCPサーバーが表示されない

1. MCP設定のcommandパスがシステムPythonではなく、.venv Pythonインタープリタを指していることを確認してください。

2. サーバーを手動で実行してインポートエラーがないか確認してください:

   .venv\Scripts\python.exe vmd_mcp_server.py

3. 設定を変更した後は、Claude Codeを完全に再起動してください。

Tclコマンドがセキュリティバリデーターによってブロックされる

execute_tclは設計上、以下のコマンドをブロックします: exec, open, file, socket, package, source, load, unload, exit, quit, proc, namespace, interp, vwait。これらの操作には、専用のツール（load_structure, render_imageなど）を使用してください。

VMDなしでのテスト — モックサーバー

# Terminal 1 — start the mock VMD server
python mock_vmd.py

# Terminal 2 — start the MCP server (connects to the mock)
python vmd_mcp_server.py

モックサーバーはポート5555でリッスンし、現実的な応答（例: DISTANCE: 3.8245, NUMFRAMES: 500）を返すため、VMDをインストールせずにパイプライン全体のテストが可能です。

引用

出版された研究や教育資料でvmd-mcpを使用する場合は、以下を引用してください:

@software{arias2026vmdmcp,
  author    = {Arias-Gaguancela, Omar},
  title     = {vmd-mcp: Plain Language Control of VMD2 via Claude MCP},
  year      = {2026},
  publisher = {GitHub},
  url       = {https://github.com/oarias/vmd-mcp},
  doi       = {10.5281/zenodo.XXXXXXX}
}

DOIは最初の安定版リリース時に登録されます。現在の引用記録についてはリポジトリを確認してください。

また、VMDも引用してください:

Humphrey, W., Dalke, A. and Schulten, K. (1996). VMD — Visual Molecular Dynamics. Journal of Molecular Graphics, 14, 33–38. https://doi.org/10.1016/0263-7855(96)00018-5

ライセンス

MITライセンス

Copyright (c) 2026 Omar Arias-Gaguancela

本ソフトウェアおよび関連ドキュメントファイルのコピーを取得したすべての者に対し、無償で本ソフトウェアを無制限に扱う権利を許可します。これには、本ソフトウェアの使用、コピー、変更、マージ、出版、配布、サブライセンス、および/または販売する権利が含まれますが、これらに限定されません。また、本ソフトウェアが提供された者がそうすることを許可されるものとします。ただし、以下の条件に従うものとします。

上記の著作権表示および本許諾表示は、本ソフトウェアのすべてのコピーまたは実質的な部分に含まれるものとします。

本ソフトウェアは「現状のまま」提供され、明示的か黙示的かを問わず、商品性、特定の目的への適合性、および非侵害の保証を含むがこれらに限定されない、いかなる種類の保証もありません。いかなる場合も、著作者または著作権者は、契約、不法行為、またはその他の原因であるかを問わず、本ソフトウェアの使用またはその他の取り扱いから生じる、あるいは関連するいかなる請求、損害、またはその他の責任に対しても責任を負いません。

について

Omar Arias-Gaguancela, PhDは、計算生物学者であり科学教育者です。あらゆるキャリアステージの研究者が高度な分子シミュレーションツールを利用できるようにすることに注力しています。

• SciLearningWorkshops LLC — 構造生物学、MDシミュレーション、AI支援研究に関するワークショップとトレーニング