HYSYS MCP Server

日本語: Claude Code / Claude Desktop から自然言語で Aspen HYSYS を操作できるようにする MCP (Model Context Protocol) サーバーです。読み取り / セッション管理 / 書き込み / フローシート構築の 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 通し・実モデルまで検証済み (詳細は実機検証状況)

安全モードについて

⚠️ まず安全に使うなら、何も設定しなくて OK です。 既定は読み取り中心の 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 でも OK。サーバーは 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 (構築) モード相当 (2024-05-30 追加)。すべて write tag で、 初期値は confirm=false のドライラン (式の確認のみ) です。

前提: HYSYS モデルのユニット操作/ポート名が必要です。詳細は hysys_list_ports を参照してください。

実機検証状況

2026-05-30 に HYSYS V14 で実機検証済み (要点のみ。詳細は docs/TODO.md)。

• オフライン: 67 passed / 2 skipped (WSL の system python でも PYTHONPATH=src pytest で実行可能 skip は m の未導入)

• 読み取り: 接続 / 情報取得 / ストリーム一覧 / 装置一戸を検証済み

• 構築系 write: create stream / create unit op / connect / delete が実機で全 OK

• MCP 通し: server.call_tool → モードゲート → handler → 実 HYSYS を確認 display: enhanced=51 本、default=27 本且つ write 系は非表示かつ拒否)

• 実モデル: 収束済みのプロセスモデル (ストリーム 47 / ユニット操作 30) で読み取り OK

開発者向け情報

ディレクトリ構成

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.py は mcp パッケージに依存しないので、HYSYS のない環境 (WSL 等) の import でもテスト可能です。

ツール追加方法

tools/<domain>.py に register(...) を 1 行足すだけです。新しい COM 操作が必要なら hysys_client.py にメソッドを追加します。

テスト

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

• オフライン: pytest

• HYSYS を使った実機テスト: scripts/ 内の live_*.py を Windows の Python から実行

注意事項

• HYSYS は Windows 専用 — Linux/macOS/WSL の Python では動きません。

• 書き込み系は HYSYS をフリーズさせることがあります — 既定の default で使い、必要時のみ enhanced にしてください。

• 本プロジェクトは音訳なしのデータ成果物に基づいています。

参考

• AspenPlus-MCP-Server (brack101)

• [MCP 仕様](https://github.com/modelcontextprotocol inc)

作成日: 2026-05-14