README.md
QCViz-MCP
A Model Context Protocol (MCP) Server for Quantum Chemistry Visualization and Electronic Structure Analysis.
개요 (Overview)
QCViz-MCP는 LLM 클라이언트(Claude Desktop 둥)가 양자화학 계산, 파일 파싱, 그리고 오비탈 시각화를 자연어로 쉽게 수행할 수 있도록 해주는 MCP 서버입니다.
핵심 기능:
- 오비탈 분석: PySCF를 활용한 IAO (Intrinsic Atomic Orbitals) 및 IBO (Intrinsic Bond Orbitals) 국소화 계산
- 결과 파싱: cclib를 통해 ORCA, Gaussian 등 16개 양자화학 프로그램 출력 파싱
- 3D 시각화: py3Dmol을 이용한 상호작용 가능한 3D 오비탈 등치면 렌더링
- 구조 조작: ASE를 이용한 분자 구조 변환
빠른 시작 가이드 (Quick Start)
설치 방법 (conda 권장)
# conda 환경 생성 (PySCF는 conda-forge에서 설치 권장)
conda create -n qcviz python=3.11 -y
conda activate qcviz
conda install -c conda-forge pyscf -y
# 나머지 의존성 설치
pip install -e ".[viz,parse,structure]"
Windows 사용자: PySCF는 Linux/macOS만 네이티브 지원합니다. Windows에서는 WSL2를 사용하세요. PySCF 없이도 파싱(
cclib), 시각화(py3Dmol), 포맷 변환(ASE) 기능은 동작합니다:pip install -e ".[dev-no-pyscf]"
테스트 및 검증
pytest -v
python examples/01_water_ibo.py # PySCF 필요
python examples/02_orca_parse_viz.py
아키텍처 다이어그램
QCViz-MCP 서버는 다양한 플러그인 형태의 백엔드와 연결되어 각 도구를 제공합니다.
MCP 클라이언트 (Claude Desktop)
│
▼
[QCViz-MCP 서버 / Tools] ─┬─ compute_ibo
├─ visualize_orbital
├─ parse_output
├─ compute_partial_charges
├─ convert_format
└─ analyze_bonding
│
▼
[백엔드 엔진] ─────────────┬─ PySCFBackend (계산, 분석)
├─ CclibBackend (파싱)
├─ Py3DmolBackend (시각화)
└─ ASEBackend (구조 조작)
라이선스
QCViz-MCP는 BSD-3-Clause 라이선스로 제공됩니다. 의존성 중 ASE는 LGPL 라이선스로 포함되어 있으나, QCViz-MCP는 이를 포함(distribute)하지 않고 참조(import)로만 사용합니다.
Tools 6
compute_iboCalculates Intrinsic Bond Orbitals using PySCF.visualize_orbitalGenerates 3D orbital isosurface renderings using py3Dmol.parse_outputParses quantum chemistry program output files using cclib.compute_partial_chargesComputes partial charges for a molecular structure.convert_formatConverts molecular structure formats using ASE.analyze_bondingPerforms bonding analysis on a molecular system.Try it
→Parse the provided ORCA output file and summarize the final electronic energy.
→Calculate the IBOs for the water molecule and visualize the HOMO orbital.
→Convert this XYZ file to a PDB format for further analysis.
→Analyze the bonding characteristics of the given molecular structure.