bradleylab/stella-mcp

A vendor-neutral Model Context Protocol (MCP)
server for creating and manipulating Stella
system dynamics models. Any compliant MCP client can build, read, validate, and
save .stmx files in the XMILE format; optional host features still vary.
What is this for?
**Stella** is a system dynamics modeling tool used for simulating complex systems in fields like ecology, biogeochemistry, economics, and engineering. This MCP server allows AI assistants to:
- **Create models from scratch** - Build stock-and-flow diagrams programmatically
- **Read existing models** - Parse and understand .stmx files
- **Validate models** - Check for errors like undefined variables or missing connections
- **Modify models** - Add stocks, flows, auxiliaries, and connectors
- **Save models** - Export valid XMILE files that open in Stella Professional
This is particularly useful for:
- Teaching system dynamics modeling
- Rapid prototyping of models through natural language
- Batch creation or modification of models
- Documenting and explaining existing models
Installation
From PyPI
From source
Requirements
- Python 3.10+
- mcp>=2.0.0, elements.
- save_as_template writes user templates to ~/.stella-mcp/templates by default (override via STELLA_MCP_TEMPLATE_DIR) and stores metadata in a .meta.json sidecar.
- Tool failures return structured MCP errors with error.code, error.category, and error.message.
- Every successful tool result retains readable text and supplies schema-validated
structuredContent described by its JSON Schema 2020-12 outputSchema.
Workspace Lifecycle
| Tool | Description |
|------|-------------|
| create_workspace | Create an isolated workspace, optionally with a caller-selected lifetime |
| revoke_workspace | Revoke a workspace and discard its in-memory models |
Model Inspection
| Tool | Description |
|------|-------------|
| list_models | List available workspace model IDs and indicate the current model |
| inspect_model | Return a structured model summary for agent inspection |
| list_modules | List modules/groups in the current model |
| list_connectors | List connector IDs, endpoints, angles, and routing metadata |
| list_variables | List all stocks, flows, and auxiliaries |
| validate_model | Check for errors (undefined variables, missing connections, etc.) |
| get_model_xml | Preview the XMILE XML output |
| render_diagram | Render the model as an SVG stock-and-flow diagram |
| simulate | Run the model via PySD and return time series + summaries (sim extra) |
| compare_scenarios | Run named what-if override sets against a baseline and report deltas (sim extra) |
| sensitivity_analysis | Sweep parameters one-at-a-time and rank their effect on an output metric (sim extra) |
| calibrate | Fit constant parameters to an observed time-series (inverse of simulate) (sim extra) |
Batch Building
build_model creates and populates a model in one call. Items apply in the
order stocks → auxs → flows → connectors → modules; the whole batch is
all-or-nothing, and on failure the error names the failing item
(error.stage + error.index). The same item arrays work on an existing
model via add_variables.
Connector sync and validation run by default (disable with
"sync_connectors": false / "validate": false); the response includes the
full structured model summary, so no follow-up inspect_model call is needed.
Tool Payload Examples
Create and switch between workspace models:
List and load templates:
Save current model as a user template:
Create and manage modules:
Rename and delete variables safely:
Update an existing variable:
Infer missing connectors from equations:
Set module view geometry directly:
Set module view style:
Auto-place module boxes from current member positions:
Target a specific model in later calls:
Read with strict compatibility checks:
Preview XML in permissive mode (default) and return compatibility warnings when present:
Valid graphical function payload:
Invalid graphical function payload (rejected):
Example Usage
Creating a simple population model
Reading and analyzing an existing model
Building a biogeochemical model
Diagram Preview
The render_diagram tool renders the model as an SVG stock-and-flow diagram
— stocks as rectangles, auxiliaries as circles, flows as valved pipes
(clouds mark sources/sinks), and dependency connectors as routed polylines. The SVG is