HYSYS MCP Server

English: Claude Code / Claude Desktop이 자연어로 Aspen HYSYS를 구동할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. read / session / write / flowsheet-build 전반에 걸친 51개 도구를 제공하며, 기본적으로 읽기 전용인 안전 모드(HYSYS_MCP_MODE)로 제어됩니다. Windows 전용(HYSYS COM)이며 HYSYS V14에서 검증되었습니다. 전체 문서는 아래 일본어 섹션을 참조하세요.

Aspen HYSYS를 Claude Code / Claude Desktop에서 자연어로 조작하기 위한 MCP (Model Context Protocol) 서버입니다.

MCP란 AI 어시스턴트(Claude 등)에 외부 도구를 안전하게 연결하기 위한 표준 프로토콜입니다. 이 서버를 통해 Claude가 HYSYS의 스트림 값이나 시뮬레이션 결과를 읽거나, (허용한 경우에만) 모델을 편집할 수 있습니다.

이것은 무엇인가?

HYSYS로 작업할 때 AI와 상담하면서 GUI를 직접 조작하는 것은 비효율적입니다. 이 서버는 Windows의 COM Automation을 통해 HYSYS를 조작하여 AI와의 채팅만으로

• 스트림 값 확인·변경

• 케이스 스터디 자동화

• 수렴 상태 실시간 모니터링

• 플로우시트 구축·편집

을 완결할 수 있게 합니다. Aspen Plus 버전 (brack101/AspenPlus-MCP-Server)은 기존에 있지만, HYSYS 버전은 미구현이었습니다(2026년 5월 시점 조사). 본 프로젝트는 그 공백을 메우는 것입니다.

Related MCP server: AspenPlus MCP Server

할 수 있는 것

• 읽기: 스트림/장치/탑 프로파일/성분/물성 패키지/수렴 상태 획득, 물질 수지 체크

• 세션 관리: 케이스 열기·닫기·저장, 복수 케이스/인스턴스 전환

• 쓰기 (선택): 스트림 조건이나 유닛 오퍼레이션 파라미터 변경, 솔버 실행, 탑 스펙 조정

• 플로우시트 구축 (선택): 스트림/장치 신규 생성·연결·삭제

• 안전 모드: 환경 변수 하나로 "읽기 전용"부터 "쓰기 허용"까지 단계적으로 제어

총 51종의 도구를 제공합니다(내역은 제공 도구 참조).

현재 상태

구현·실기 검증 모두 완료되었습니다(2026-05-30 시점).

• registry 방식으로 리팩터링 + 모드 게이트 구현 완료

• 오프라인 테스트 67 passed / 2 skipped

• 실기(HYSYS V14)에서 읽기·구축계 쓰기·MCP 통과·실모델까지 검증 완료 (자세한 내용은 실기 검증 현황)

안전 모드에 대하여

⚠️ 안전하게 사용하려면 아무것도 설정하지 않아도 됩니다. 기본값은 읽기 중심의 default 모드로 시작하며, 모델을 변경하는 도구는 공개되지 않습니다.

환경 변수 HYSYS_MCP_MODE로 "공개되는 도구의 부작용 수준"을 전환합니다. 각 도구에는 read / session / write 태그가 붙어 있으며, 모드에 따라 목록(list_tools)에서 제외되고, 호출되어도 HYSYS에 연결하기 전에 거부됩니다.

• 기본값인 default에서는 set_stream / run / 구축계 등의 쓰기 도구가 공개되지 않습니다. "열람과 저장만"의 안전한 상태로 시작할 수 있습니다.

• 쓰기를 사용할 때만 HYSYS_MCP_MODE=enhanced를 설정합니다 (쓰기 기능을 활성화하는 경우).

• 유효하지 않은 값을 설정한 경우 안전 측으로 기울어 readonly로 시작합니다.

아키텍처 개요

┌─────────────────┐         ┌──────────────────────┐         ┌─────────────┐
│  Claude Code    │  MCP    │  HYSYS MCP Server    │   COM   │   HYSYS     │
│  (WSL or Win)   │ stdio   │  (Windows Python)    │  pywin32│  (Windows)  │
└─────────────────┘  <──>   └──────────────────────┘  <──>   └─────────────┘

• MCP server는 Windows 네이티브 Python에서 동작하며 pywin32를 통해 HYSYS.Application COM 오브젝트에 연결합니다.

• Claude Code / Claude Desktop과는 stdio로 통신합니다 (Claude Code 본체가 WSL에 있어도 서버는 Windows Python을 호출합니다).

• 구현 상세는 docs/ARCHITECTURE.md를 참조하세요.

셋업

필요 환경

• Windows 10/11

• Aspen HYSYS V12 이상 (V14에서 동작 확인 완료)

• Python 3.10+ (Windows 네이티브. WSL의 Python에서는 동작하지 않습니다)

• pywin32

⚠️ HYSYS는 Windows 전용입니다. COM Automation을 사용하므로 Linux/macOS나 WSL의 Python에서는 동작하지 않습니다 (Claude Code 본체는 WSL도 가능. 서버만 Windows Python).

설치

# Windows PowerShell
cd path\to\hysys-mcp
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e .

Claude Desktop / Claude Code 설정

%APPDATA%\Claude\claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "hysys": {
      "command": "C:\\path\\to\\hysys-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "hysys_mcp.server"]
    }
  }
}

• command는 각자의 clone 위치의 venv\Scripts\python.exe 절대 경로로 바꿔 주세요.

• 이 설정은 HYSYS_MCP_MODE를 지정하지 않으므로 기본값인 **default (읽기 + 저장)**로 시작합니다.

쓰기 기능을 활성화하는 경우

스트림 값 변경·솔버 실행·플로우시트 구축을 사용하려면 env에서 HYSYS_MCP_MODE=enhanced를 설정합니다. 서버 측 환경 변수만으로 완결되므로 사용자별로 각자의 설정 파일에서 전환할 수 있습니다.

{
  "mcpServers": {
    "hysys": {
      "command": "C:\\path\\to\\hysys-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "hysys_mcp.server"],
      "env": { "HYSYS_MCP_MODE": "enhanced" }
    }
  }
}

⚠️ 쓰기 계열은 HYSYS를 프리즈시킬 수 있습니다. 기본값이 안전 측인 default인 것은 이 때문입니다. 먼저 읽기로 시도하고, 쓰기가 필요해진 후에 enhanced로 올리는 운영을 권장합니다. Claude Code 측에서 개별 도구를 permissions.deny로 차단할 수도 있습니다 (이는 사용자 로컬 설정이며 배포물에는 포함되지 않습니다).

제공 도구

구현 완료 51종. 태그에 따라 공개 모드가 결정됩니다 (안전 모드에 대하여).

read 도구 (21)

hysys_list_streams hysys_get_stream hysys_list_unit_ops hysys_get_status hysys_list_column_specs hysys_get_column_profile hysys_balance_check hysys_get_stream_phys hysys_introspect hysys_list_components hysys_find_streams hysys_find_ops hysys_list_ports 외

session 도구 (6)

hysys_open hysys_close hysys_reconnect hysys_list_instances → hysys_switch_instance hysys_set_active_case hysys_save

write 도구 (24)

hysys_set_stream hysys_set_unit_op_param hysys_run hysys_reset hysys_case_study hysys_set_column_spec 계열 hysys_column_run hysys_set_adjust_target hysys_call_method hysys_set_property 외

플로우시트 구축 도구

AspenPlus-MCP의 enhanced (구축) 모드에 해당 (2026-05-30 추가). 모두 write 태그이며, 기본값은 confirm=false의 드라이런(실행 내용 확인만)입니다.

사용 전제: 성분 + Fluid Package가 정의된 케이스가 필요합니다. 빈 케이스에서는 create_stream 자체가 실패합니다 (HYSYS 사양. AspenPlus-MCP도 성분/물성은 기존 케이스 전제).

disconnect_stream은 해당 HYSYS V14 COM 빌드에서는 미지원입니다 (연결점을 비우는 API가 존재하지 않기 때문). 실행하면 supported:false와 대체 수단(연결 변경은 connect_stream, 제거는 delete_object, 완전한 분리는 GUI)을 반환합니다.

성분/반응/Fluid Package 편집은 환경 차이가 커서 전용 도구를 준비하지 않았습니다 (hysys_call_method / hysys_set_property로 도달 가능). 타입 이름이나 포트 이름이 불명확할 때는 hysys_find_ops / hysys_list_ports로 확인하세요.

실기 검증 현황

2026-05-30에 HYSYS V14에서 실기 검증 완료 (요점만. 상세는 docs/TODO.md).

• 오프라인: 67 passed / 2 skipped (WSL의 system python에서도 PYTHONPATH=src pytest로 실행 가능. skip은 mcp/win32 미도입에 따른 환경 제약)

• 읽기: connect / list_cases / list_streams / list_unit_ops 등을 실기 확인

• 구축계 write: create_stream / create_unit_op / connect_stream / list_ports / delete_object가 실기에서 전부 OK, 정리 후 모델 무손상 (잔해 제로)

• 망라 검증: energy 스트림, 장치 타입 mixer / heater / separator (=flashtank) / valve / cooler, feed / product / energy 포트 연결을 커버

• MCP 통과: server.call_tool → 모드 게이트 → handler → 실 HYSYS 확인 (enhanced=51개, default=27개로 write 계열은 비표시 및 호출 거부)

• 실모델: 수렴 완료된 실 프로세스 모델 (스트림 47 / 유닛 오퍼레이션 30 규모)에서 읽기 전부 OK ＋ 고립 오브젝트의 create→delete를 실시하여 모델 무손상 (47→47 / 30→30)·Save 미실행 확인

재현 스크립트는 scripts/ 아래 (live_probe.py / live_build_test.py / live_build_test_full.py / live_mcp_passthrough.py / live_prod_test.py).

개발자용 정보

디렉터리 구성

src/hysys_mcp/
  registry.py      # ToolSpec(tool+handler+tag) / モードゲート / JSON 正規化 (mcp 非依存)
  server.py        # 薄い adapter: registry → list_tools / call_tool ディスパッチ
  tools/           # ドメイン別ツール定義
    connection.py  streams.py  unit_ops.py  columns.py
    solver.py      logical.py  fluid.py     generic.py
    build.py       # フローシート構築 (create/connect/delete/ports)
  hysys_client.py  # COM 層 (HYSYS.Application 操作。registry 層からは触らない)
tests/             # オフラインテスト (registry / basic)
scripts/           # 実機検証スクリプト
docs/              # ARCHITECTURE.md / TODO.md

server.py는 도구 등록도 디스패치도 registry에 위임하는 얇은 계층입니다. registry.py는 mcp 패키지에 의존하지 않으므로 HYSYS가 없는 환경 (WSL 등)에서도 import할 수 있고, 레지스트리 계층의 단위 테스트가 돌아갑니다. 설계 사상은 AspenPlus-MCP의 구성 분할을 이식한 것입니다.

도구 추가 방법

tools/<domain>.py에 register(...)를 1줄 추가하면 됩니다 (기존의 거대한 if/elif는 폐지). 새로운 COM 조작이 필요하면 hysys_client.py에 메서드를 추가합니다.

테스트

# WSL/Linux でも registry 層のテストは回せる
PYTHONPATH=src pytest -q

실기 테스트 (HYSYS COM이 필요한 것)는 Windows의 venv Python에서 scripts/의 각 스크립트를 실행합니다.

주의사항

• HYSYS는 Windows 전용 — Linux/macOS/WSL의 Python에서는 동작하지 않습니다.

• 쓰기 계열은 HYSYS를 프리즈시킬 수 있음 — 기본값인 default에서 시작하고, 필요 시에만 enhanced로 올리세요.

• 구축 계열은 성분 + Fluid Package 정의된 케이스가 전제 — 빈 케이스에서는 생성에 실패합니다.

• disconnect_stream은 해당 V14 COM 빌드에서는 미지원 — 대체 수단은 위 참조.

참고 자료

• Aspen Plus MCP Server (brack101) — Aspen Plus 버전, 설계 참고

• Aspen HYSYS Customization Guide (PDF, archive.org 미러) — COM Automation 공식 레퍼런스 (AspenTech, V7.3). 원본은 AspenTech 지원 포털에서 배포

• Model Context Protocol 사양 — MCP 표준

Created: 2026-05-14