HYSYS MCP Server

Inglés: Un servidor MCP (Model Context Protocol) que permite a Claude Code / Claude Desktop controlar Aspen HYSYS en lenguaje natural. 51 herramientas en read / session / write / flowsheet-build, controladas por un modo seguro (HYSYS_MCP_MODE) que es de solo lectura por defecto. Solo Windows (HYSYS COM), verificado en HYSYS V14. Consulte las secciones en japonés a continuación para la documentación completa.

Un servidor MCP (Model Context Protocol) para operar Aspen HYSYS desde Claude Code / Claude Desktop en lenguaje natural.

MCP es un protocolo estándar para conectar de forma segura herramientas externas a asistentes de IA (como Claude). A través de este servidor, Claude puede leer los valores de las corrientes de HYSYS y los resultados de simulación, y (solo si está permitido) editar el modelo.

¿Qué es esto?

Trabajar con HYSYS operando la GUI manualmente mientras se consulta a la IA es ineficiente. Este servidor controla HYSYS a través de COM Automation de Windows y permite completar, solo con el chat con la IA:

• Consulta y modificación de valores de corrientes

• Automatización de estudios de caso

• Monitoreo en tiempo real del estado de convergencia

• Construcción y edición de diagramas de flujo

La versión de Aspen Plus (brack101/AspenPlus-MCP-Server) ya existía, pero la versión de HYSYS no estaba implementada (investigación de mayo de 2026). Este proyecto llena ese vacío.

Related MCP server: AspenPlus MCP Server

Funcionalidades

• Lectura: obtención de corrientes/equipos/perfiles de columna/componentes/paquetes de propiedades/estado de convergencia, verificación de balance de materia

• Gestión de sesión: abrir/cerrar/guardar casos, cambio entre múltiples casos/instancias

• Escritura (opcional): modificación de condiciones de corrientes y parámetros de operaciones unitarias, ejecución del solver, ajuste de especificaciones de columna

• Construcción de diagramas de flujo (opcional): creación, conexión y eliminación de corrientes/equipos

• Modo seguro: control gradual desde "solo lectura" hasta "escritura habilitada" con una sola variable de entorno

Se proporcionan 51 tipos de herramientas en total (consulte Herramientas proporcionadas para el desglose).

Estado actual

Implementación y verificación en equipo real completadas (al 2026-05-30).

• Refactorización al método registry + implementación de la compuerta de modo

• Pruebas offline 67 passed / 2 skipped

• Verificado en equipo real (HYSYS V14) para lectura, escritura de construcción, MCP completo y modelo real (detalles en Estado de verificación en equipo real)

Acerca del modo seguro

⚠️ Si desea usarlo de forma segura, no necesita configurar nada. Por defecto se inicia en modo default centrado en lectura, y las herramientas que modifican el modelo no se publican.

La variable de entorno HYSYS_MCP_MODE cambia el "nivel de efectos secundarios de las herramientas publicadas". Cada herramienta tiene una etiqueta read / session / write, y según el modo se excluye de la lista (list_tools), y aunque se llame, se rechaza antes de conectarse a HYSYS.

• En el default por defecto, las herramientas de escritura como set_stream / run / construcción no se publican. Puede comenzar en un estado seguro de "solo visualización y guardado".

• Configure HYSYS_MCP_MODE=enhanced solo cuando necesite usar la escritura (Para habilitar la función de escritura).

• Si se establece un valor no válido, se inicia en readonly por seguridad.

Resumen de la arquitectura

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

• El servidor MCP funciona con Python nativo de Windows y se conecta al objeto COM HYSYS.Application a través de pywin32.

• Se comunica con Claude Code / Claude Desktop mediante stdio (incluso si Claude Code está en WSL, el servidor llama a Python de Windows).

• Consulte docs/ARCHITECTURE.md para los detalles de implementación.

Configuración

Requisitos

• Windows 10/11

• Aspen HYSYS V12 o posterior (verificado en V14)

• Python 3.10+ (nativo de Windows. No funciona con Python de WSL)

• pywin32

⚠️ HYSYS es solo para Windows. Como utiliza COM Automation, no funciona desde Python de Linux/macOS o WSL (Claude Code puede estar en WSL; solo el servidor necesita Python de Windows).

Instalación

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

Configuración de Claude Desktop / Claude Code

Añada lo siguiente a %APPDATA%\Claude\claude_desktop_config.json:

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

• Reemplace command con la ruta absoluta de venv\Scripts\python.exe en su clon.

• Esta configuración no especifica HYSYS_MCP_MODE, por lo que se inicia en el default (lectura + guardado) por defecto.

Para habilitar la función de escritura

Si desea modificar valores de corrientes, ejecutar el solver o construir diagramas de flujo, configure HYSYS_MCP_MODE=enhanced en env. Se completa solo con la variable de entorno del servidor, por lo que cada usuario puede cambiarlo en su propio archivo de configuración.

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

⚠️ Las operaciones de escritura pueden congelar HYSYS. Por eso el valor por defecto es el default seguro. Se recomienda probar primero con lectura y subir a enhanced solo cuando sea necesario escribir. También puede bloquear herramientas individuales con permissions.deny en Claude Code (esto es una configuración local del usuario y no se incluye en la distribución).

Herramientas proporcionadas

51 tipos implementados. El modo de publicación se determina por la etiqueta (Acerca del modo seguro).

Herramientas 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 y otras

Herramientas session (6)

hysys_open hysys_close hysys_reconnect hysys_list_instances → hysys_switch_instance hysys_set_active_case hysys_save

Herramientas write (24)

hysys_set_stream hysys_set_unit_op_param hysys_run hysys_reset hysys_case_study hysys_set_column_spec y similares hysys_column_run hysys_set_adjust_target hysys_call_method hysys_set_property y otras

Herramientas de construcción de diagramas de flujo

Equivalente al modo enhanced (construcción) de AspenPlus-MCP (añadido el 2026-05-30). Todas con etiqueta write, y por defecto son de ejecución en seco con confirm=false (solo confirmación de lo que se ejecutará).

Requisito previo: se necesita un caso con componentes + Fluid Package definidos. En un caso vacío, create_stream falla (especificación de HYSYS. AspenPlus-MCP también presupone casos existentes con componentes/propiedades).

disconnect_stream no es compatible con esta compilación COM de HYSYS V14 (no existe una API para vaciar el punto de conexión). Al ejecutarlo devuelve supported:false y alternativas (reconexión con connect_stream, eliminación con delete_object, desconexión completa con la GUI).

No se proporcionan herramientas dedicadas para editar componentes/reacciones/Fluid Package debido a las grandes diferencias entre entornos (se puede acceder con hysys_call_method / hysys_set_property). Si no conoce los nombres de tipos o puertos, consulte hysys_find_ops / hysys_list_ports.

Estado de verificación en equipo real

Verificado en equipo real con HYSYS V14 el 2026-05-30 (solo puntos clave. Detalles en docs/TODO.md).

• Offline: 67 passed / 2 skipped (también se puede ejecutar con PYTHONPATH=src pytest en el Python del sistema de WSL. Los skipped se deben a restricciones del entorno sin mcp/win32)

• Lectura: connect / list_cases / list_streams / list_unit_ops, etc. verificados en equipo real

• Escritura de construcción: create_stream / create_unit_op / connect_stream / list_ports / delete_object todos OK en equipo real, modelo intacto después de la limpieza (cero residuos)

• Verificación exhaustiva: cubre corrientes de energía, tipos de equipo mixer / heater / separator (=flashtank) / valve / cooler, conexión de puertos feed / product / energy

• MCP completo: verificado server.call_tool → compuerta de modo → handler → HYSYS real (enhanced=51, default=27 con write ocultas y rechazadas al llamarlas)

• Modelo real: lectura completa OK en un modelo de proceso real convergido (escala de 47 corrientes / 30 operaciones unitarias)

  • se realizó create→delete de un objeto aislado, confirmando modelo intacto (47→47 / 30→30) y Save no ejecutado

Los scripts de reproducción están en scripts/ (live_probe.py / live_build_test.py / live_build_test_full.py / live_mcp_passthrough.py / live_prod_test.py).

Información para desarrolladores

Estructura de directorios

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 es una capa delgada que delega tanto el registro de herramientas como el despacho al registry. registry.py no depende del paquete mcp, por lo que se puede importar en entornos sin HYSYS (como WSL), y las pruebas unitarias de la capa de registry se ejecutan. El diseño es una adaptación de la división de componentes de AspenPlus-MCP.

Cómo añadir herramientas

Solo hay que añadir una línea register(...) en tools/<domain>.py (se eliminaron los enormes if/elif anteriores). Si necesita nuevas operaciones COM, añada métodos a hysys_client.py.

Pruebas

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

Las pruebas en equipo real (las que requieren HYSYS COM) se ejecutan con el Python del venv de Windows usando los scripts de scripts/.

Notas

• HYSYS es solo para Windows — no funciona con Python de Linux/macOS/WSL.

• Las operaciones de escritura pueden congelar HYSYS — comience con el default por defecto y suba a enhanced solo cuando sea necesario.

• La construcción presupone casos con componentes + Fluid Package definidos — falla en casos vacíos.

• disconnect_stream no es compatible con esta compilación COM de V14 — consulte las alternativas arriba.

Referencias

• Aspen Plus MCP Server (brack101) — versión de Aspen Plus, referencia de diseño

• Aspen HYSYS Customization Guide (PDF, espejo de archive.org) — referencia oficial de COM Automation (AspenTech, V7.3). El original se distribuye en el portal de soporte de AspenTech

• Especificación de Model Context Protocol — estándar MCP

Creado: 2026-05-14