home / mcp / stella mcp server

Stella MCP Server

Provides an MCP server to create, read, validate, and save Stella XMILE models via simple tools.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "bradleylab-stella-mcp": {
      "command": "stella-mcp",
      "args": []
    }
  }
}

You run Stella MCP Server to programmatically create, read, validate, modify, and save Stella XMILE models. This enables AI assistants and automation to build complex system dynamics models from scratch or adapt existing ones with confidence, then export ready-to-use XMILE files for Stella Professional or Stella Architect.

How to use

You connect a client to the Stella MCP Server and issue high-level modeling commands through the MCP interface. Use the available tools to create a new model, add stocks, flows, and auxiliaries, connect variables, validate the model, read existing models from .stmx files, and save your work as XMILE-compatible files.

How to install

Prerequisites: Python 3.10+ and a working Python environment.

Install the MCP server package from PyPI or install from source to run locally.

pip install stella-mcp
```

```
git clone https://github.com/bradleylab/stella-mcp.git
cd stella-mcp
pip install -e .

Additional configuration and notes

Configuration examples show how to wire the MCP server into your Claude client. You can configure a local stdio-based MCP server using the CLI entry point stella-mcp or launch via Python in development mode with python -m stella_mcp.server.

Development mode command example (stdio):
```
{
  "mcpServers": {
    "stella_mcp": {
      "command": "python",
      "args": ["-m", "stella_mcp.server"],
      "cwd": "/path/to/stella-mcp"
    }
  }
}
```
You would adjust the working directory to where you cloned the project.

Available tools

create_model

Create a new model with a name and time settings (start, stop, dt, method)

read_model

Load an existing .stmx file

save_model

Save the current model to a .stmx file

add_stock

Add a stock (reservoir) with an initial value and units

add_flow

Add a flow between stocks with an equation

add_aux

Add an auxiliary variable (parameter or calculation)

add_connector

Add a dependency connector between variables

list_variables

List all stocks, flows, and auxiliaries

validate_model

Check for errors such as undefined variables, missing connections, and mass-balance issues

get_model_xml

Preview the XMILE XML output