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는 이러한 격차를 해소합니다.

이 도구를 사용하면 연구자는 단일 대화 내에서 궤적 파일로부터 출판 품질의 그림과 정량적 측정값을 얻을 수 있으며, Tcl 지식이 전혀 필요하지 않습니다. 또한 이 분야에 입문하는 교육생과 학생들의 진입 장벽을 낮추어 소프트웨어 구문보다는 생물학 자체에 집중할 수 있게 합니다. 보안을 고려한 설계(경로 허용 목록, Tcl 명령 검증) 덕분에 공유 또는 교육용 컴퓨팅 환경에서도 안전하게 배포할 수 있습니다.

주요 기능

• 23개의 MCP 도구: 구조 로드, 궤적 탐색, 표현, 측정, 렌더링 및 Tcl 패스스루 지원

• 자연어 인터페이스: Claude에게 단백질 시각화, 거리 측정, RMSD 계산 등을 평문으로 요청 가능

• 서브프로세스 모드: Windows에서 수동 Tcl 스크립팅 없이 VMD2를 헤드리스(headless)로 실행 및 제어

• 보안 우선 설계: 모든 파일 경로는 구성 가능한 허용 목록에 따라 검증되며, Tcl 명령은 위험한 작업(exec, open, file, socket 등)을 차단하도록 살균됨

• Windows 네이티브: CREATE_NO_WINDOW 서브프로세스 수정 사항이 포함되어 작동 중 불필요한 콘솔 창이 나타나지 않음

• 소켓 모드: localhost:5555에서 미리 실행 중인 VMD 인스턴스에 선택적으로 연결 가능

• Mock 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에게 물어보세요: "VMD에 사용할 수 있는 MCP 도구는 무엇인가요?" 서버가 올바르게 연결되었다면 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 없이 테스트 — Mock 서버

# 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

Mock 서버는 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 지원 연구에 대한 워크숍 및 교육