add_aux
Add an auxiliary variable (parameter or intermediate calculation) to the current model
LABSCO SUMMARY
The construction tools are all-or-nothing and name the item that failed, which is what makes building a model by agent survivable.
Both batch builders leave the model unchanged on any item error and report the failing item by stage and index, so a half-built model is not a state you can end up in. Two limits are stated rather than left to be discovered: simulation integrates with Euler regardless of the model's own method setting, and calibration rejects stocks because overriding one pins it to a constant instead of setting its initial value. Connector sync and validation run by default on the batch build, which makes the response double as an inspection of what was just built.
What it is
A vendor-neutral server for system dynamics models in the XMILE format: model construction, diagram layout, file and template handling, simulation, scenario comparison, sensitivity analysis, calibration, and workspace isolation. What it saves is a .stmx file that opens in Stella Professional.
What you get
- build_model creates and populates a model in one call — sim specs, stocks, auxiliaries, flows, connectors and modules — all-or-nothing, so on any item error nothing is registered and the error names the failing item by stage and index; add_variables does the same against an existing model.
- Element-level construction: add_stock and update_stock, add_flow and update_flow with their source and destination stocks, add_aux and update_aux, add_connector, rename_variable, which updates dependent references, and delete_variable, which cleans up connectors and module membership.
- sync_connectors_from_equations adds the dependency connectors implied by flow and auxiliary equations rather than making you draw each one.
- Modules for organisation: create_module, add_to_module, remove_from_module, rename_module, delete_module, set_module_view, set_module_style and auto_place_module_boxes.
- Diagram work: set_connector_routing with an angle and explicit waypoints, and render_diagram, which returns the SVG inline for clients without file access and can also write it to a file, running auto-layout first by default.
- Files and templates: save_model and read_model for .stmx files, get_model_xml for the XMILE representation, and list_templates, get_template_info, load_template and save_as_template.
- Analysis: simulate returns downsampled time series with per-variable initial, final, minimum and maximum values; compare_scenarios runs named parameter-override scenarios against a baseline and reports how each diverges; sensitivity_analysis sweeps each parameter one at a time and reports a slope and a normalised elasticity for ranking; calibrate fits constant parameters to an observed series.
- Inspection: inspect_model, validate_model, list_variables, list_modules, list_connectors and list_models.
- Workspaces: create_workspace for isolated, stateful tool calls, and revoke_workspace to discard everything held in one.
Requirements
Python, installed from PyPI. Simulation is an optional extra rather than part of the base install: the simulate, scenario, sensitivity and calibrate tools need the PySD dependency, which the sim extra pulls in — everything to do with building, validating and saving models works without it. On current-protocol clients, create a workspace first and pass its id on the stateful calls; older stdio clients get one process-local workspace and may omit it. Calibration accepts only constant auxiliaries and flows, rejects stocks, and needs observation times inside the simulated range.
Setup effort
One command — pip install stella-mcp
USE CASES
01
Building a stock-and-flow model in one call
Describe the stocks, flows, auxiliaries and connectors together — nothing is registered unless all of it validates.
02
Getting the connectors right without drawing every arrow
Write the equations, then let the server add the dependency connectors they imply and list what it drew.
03
Running the model and reading what happened
Simulate and take the downsampled series with per-variable initial, final, minimum and maximum values, rather than a wall of timesteps.
04
Testing what-if scenarios against a baseline
Name each scenario as a set of parameter overrides and read how far each one moves the outcome.
05
Fitting a model to data you actually observed
Calibrate the constant parameters against the observed series instead of tuning them by hand.
06
Producing a diagram someone else can read
Auto-place the module boxes, render the stock-and-flow diagram to SVG, and save the model where Stella can open it.
44 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
add_connector
Add a connector (dependency arrow) between variables
add_flow
Add a flow between stocks in the current model
add_stock
Add a stock (reservoir) to the current model
add_to_module
Add variables to an existing module
add_variables
Add multiple stocks, auxiliaries, flows, connectors, and/or modules to an existing model in one call. All-or-nothing — on any item error the model is left unchanged and the error names the failing item (stage + index).
auto_place_module_boxes
Auto-place module view boxes around their member variables
build_model
Create and populate a model in one call: sim specs, stocks, auxiliaries, flows, connectors, and modules. All-or-nothing — on any item error nothing is registered and the error names the failing item (stage + index). Connector sync and validation run by default, so the response doubles as an inspection.
calibrate
Fit constant model parameters to an observed time-series — the inverse of simulate. Only constant auxiliaries/flows can be calibrated (stocks are rejected: overriding a stock pins it to a constant rather than setting its initial value). least_squares (default) reports a linearized std_error; differential_evolution is a global, seeded alternative requiring bounds. Observation times must lie within the model window (no extrapolation). Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
compare_scenarios
Run several named what-if scenarios (each a set of constant parameter overrides) against a baseline and report how each diverges: per-variable final/max absolute deltas and final percent change. Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
create_model
Create a new Stella model with specified time settings
create_module
Create a logical module/group for organizing variables
create_workspace
Create an isolated application workspace for stateful Stella tool calls. The returned ID routes state and is not an authorization credential.
delete_model
Remove a model from the current session. Saved .stmx files are not touched. model_id is required — there is deliberately no implicit 'delete current model'.
delete_module
Delete a module
delete_variable
Delete a stock/flow/aux and clean connectors/module membership
get_model_xml
Get the XMILE XML representation of the current model (for preview)
get_template_info
Get detailed metadata for one template
inspect_model
Return a structured summary of the current model for agent inspection
list_connectors
List connector metadata (uid, endpoints, angle, routing lock/points)
list_models
List all model IDs available in the current session
list_modules
List modules/groups in the current model
list_templates
List built-in and user-defined templates
list_variables
List all variables (stocks, flows, auxiliaries) in the current model
load_template
Load a template into the current session as a model
read_model
Read an existing .stmx file and load it as the current model
remove_from_module
Remove variables from an existing module
rename_module
Rename an existing module
rename_variable
Rename a stock/flow/aux and update dependent references
render_diagram
Render the current model as an SVG stock-and-flow diagram. The SVG is returned inline (for clients without file access) and optionally written to a file. Defaults to running auto-layout first so freshly built models render sensibly.
revoke_workspace
Revoke a workspace and discard all models stored in it.
save_as_template
Save the current model as a user-defined template
save_model
Save the current model to a .stmx file
sensitivity_analysis
One-at-a-time sensitivity: sweep each parameter across a range (holding the others at their baseline) and report how one chosen output metric responds, with a range slope and a baseline-normalized elasticity for ranking. Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
set_connector_routing
Set connector angle and/or explicit routing waypoints
set_module_style
Set module box visual style in the diagram view
set_module_view
Set explicit view box geometry for a module
set_sim_specs
Update simulation time settings on an existing model
simulate
Run the model and return downsampled time series with per-variable summaries (initial/final/min/max). Requires the optional pysd dependency (pip install 'stella-mcp[sim]'). Integration is Euler regardless of the model's method setting.
sync_connectors_from_equations
Add missing dependency connectors inferred from flow and auxiliary equations
update_aux
Update auxiliary variable fields
update_flow
Update flow fields while preserving structural stock links
update_stock
Update stock fields while preserving relationships
validate_model
Validate the current model for errors and warnings
BEFORE YOU INSTALL
What to know first
Tools you get
44 tools when we connected. simulate, compare_scenarios, sensitivity_analysis and calibrate register but need pip install 'stella-mcp[sim]' to work. save_results_csv and the other save_*_csv names are arguments, not tools.
Requires
Python 3.10+
Where it runs
All 3 documented clients run the server on your machine.
CONTEXT COST
Heavy Standing cost
Rated by the size of the 44 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install stella-mcpMCP Clients
Claude Desktop, Claude Code
JSON
{
"mcpServers": {
"stella": {
"command": "stella-mcp"
}
}
}Any MCP client — uvx
ANY MCP CLIENT — UVX · JSON
{
"mcpServers": {
"stella": {
"command": "uvx",
"args": [
"stella-mcp"
]
}
}
}
