ACM MCP Server

An MCP (Model Context Protocol) server that automates Aspen Custom Modeler (ACM) via COM. Designed for use with Claude Code to open .acmf files, run simulations, and read/write variable values programmatically.

Features

• 15 MCP tools for full ACM automation: session management, steady-state and dynamic simulation, variable access, and task control
• Session-based — manage multiple ACM instances
• COM automation via comtypes (not win32com, which has known VARIANT issues with ACM)
• Comprehensive docs — includes condensed ACM V15 Help (2,227 pages distilled to 10 markdown files)

Requirements

• Windows (COM automation is Windows-only)
• Python 3.10+
• Aspen Custom Modeler V15 installed
• Claude Code (or any MCP-compatible client)

Installation

pip install "mcp[cli]>=1.0.0" "comtypes>=1.4.0"

Setup with Claude Code

Add this to your project's .mcp.json:

{
  "mcpServers": {
    "acm": {
      "command": "python",
      "args": ["<path-to>/acm-mcp/server.py"]
    }
  }
}

Restart Claude Code after first setup to pick up the server.

Tools

Session Tools

Tool	Description
open_acm	Open an .acmf file and create a session
connect_acm	Connect to an already-running ACM instance
close_acm	Close a session and quit ACM
list_acm_sessions	List all active sessions

Simulation Tools

Tool	Description
run_steady_state	Run steady-state simulation
run_dynamic	Run dynamic simulation to a specified end time
get_simulation_status	Get current status, DOF, convergence info
reset_simulation	Reset to initial conditions

Variable Tools

Tool	Description
get_variable	Get a variable by dot-notation path (e.g. B1.Tank.h)
set_variable	Set a variable's value
get_variables_bulk	Get multiple variables at once
find_variables	Find variables matching a wildcard pattern

Task Tools

Tool	Description
create_task	Create a task on the flowsheet
activate_task	Activate a task for dynamic simulation
deactivate_task	Deactivate a task

Quick Start

1. open_acm("path/to/model.acmf")
2. run_steady_state("model")
3. get_variable("model", "B1.Tank.h")  →  "B1.Tank.h = 40.0 [cm] (Free)"

Dynamic step change procedure

To observe transient dynamics after a step change:

1. run_steady_state at initial conditions
2. run_dynamic to a small time (e.g. 0.001) — locks state variables at old SS
3. set_variable to apply the step change
4. run_dynamic to successive times, reading variables at each point

Important: Do NOT set_variable before the first run_dynamic — ACM re-initializes state variables at the new conditions, producing an instant jump to new SS with no visible transient.

Documentation

Detailed documentation is in docs/:

• overview.md — Architecture and design decisions
• tools.md — Full tool reference with parameters and examples
• com-api.md — ACM COM API notes and gotchas
• Error_Logbook.txt — Known ACM errors and fixes
• acm_help/ — Condensed ACM V15 Help system (10 files covering modeling language, solver options, library reference, examples, etc.)

Architecture

server.py              # FastMCP entry point, 15 tool registrations
acm_manager.py         # COM lifecycle: subprocess launch, GetActiveObject, sessions
tools/
  session_tools.py     # open, connect, close, list
  simulation_tools.py  # run steady/dynamic, status, reset
  variable_tools.py    # get, set, bulk get, find
  task_tools.py        # create, activate, deactivate
docs/                  # Documentation and ACM Help reference

License

MIT