HYSYS MCP Server

英文：这是一个 MCP (Model Context Protocol) 服务器，可让 Claude Code / Claude Desktop 以自然语言驱动 Aspen HYSYS。提供 read / session / write / flowsheet-build 共 51 种工具， 由安全模式（HYSYS_MCP_MODE）控制，默认只读。仅支持 Windows（HYSYS COM）， 已在 HYSYS V14 上验证。完整文档请参阅下方章节。

这是一个用于通过 Claude Code / Claude Desktop 以自然语言操作 Aspen HYSYS 的 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 的 tag，根据模式会从列表 (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 种。根据 tag 决定公开模式（关于安全模式）。

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 tag， 默认情况下是 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， 并且可以运行 registry 层的单元测试。设计思想移植自 AspenPlus-MCP 的组件划分。

添加工具的方法

只需在 tools/<domain>.py 中添加一行 register(...)（废弃了以往庞大的 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 标准

创建于：2026-05-14