Stella MCP Server

1# Stella MCP Server
2 
3A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for creating and manipulating [Stella](https://www.iseesystems.com/store/products/stella-professional.aspx) system dynamics models. This enables AI assistants like Claude to programmatically build, read, validate, and save `.stmx` files in the XMILE format.
4 
5## What is this for?
6 
7**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:
8 
9- **Create models from scratch** - Build stock-and-flow diagrams programmatically
10- **Read existing models** - Parse and understand .stmx files
11- **Validate models** - Check for errors like undefined variables or missing connections
12- **Modify models** - Add stocks, flows, auxiliaries, and connectors
13- **Save models** - Export valid XMILE files that open in Stella Professional
14 
15This is particularly useful for:
16- Teaching system dynamics modeling
17- Rapid prototyping of models through natural language
18- Batch creation or modification of models
19- Documenting and explaining existing models
20 
21## Installation
22 
23### From PyPI
24 
25```bash
26pip install stella-mcp
27```
28 
29### From source
30 
31```bash
32git clone https://github.com/bradleylab/stella-mcp.git
33cd stella-mcp
34pip install -e .
35```
36 
37### Requirements
38 
39- Python 3.10+
40- `mcp>=1.0.0`
41 
42## Configuration
43 
44### Claude Desktop
45 
46Add to your `claude_desktop_config.json`:
47 
48```json
49{
50  "mcpServers": {
51    "stella": {
52      "command": "stella-mcp"
53    }
54  }
55}
56```
57 
58### Claude Code
59 
60Add to your `.claude/settings.json`:
61 
62```json
63{
64  "mcpServers": {
65    "stella": {
66      "command": "stella-mcp"
67    }
68  }
69}
70```
71 
72### Development mode
73 
74If running from source:
75 
76```json
77{
78  "mcpServers": {
79    "stella": {
80      "command": "python",
81      "args": ["-m", "stella_mcp.server"],
82      "cwd": "/path/to/stella-mcp"
83    }
84  }
85}
86```
87 
88## Available Tools
89 
90### Model Creation & I/O
91 
92| Tool | Description |
93|------|-------------|
94| `create_model` | Create a new model with name and time settings (start, stop, dt, method) |
95| `read_model` | Load an existing .stmx file |
96| `save_model` | Save model to a .stmx file |
97 
98### Model Building
99 
100| Tool | Description |
101|------|-------------|
102| `add_stock` | Add a stock (reservoir) with initial value and units |
103| `add_flow` | Add a flow between stocks with an equation |
104| `add_aux` | Add an auxiliary variable (parameter or calculation) |
105| `add_connector` | Add a dependency connector between variables |
106 
107### Model Inspection
108 
109| Tool | Description |
110|------|-------------|
111| `list_variables` | List all stocks, flows, and auxiliaries |
112| `validate_model` | Check for errors (undefined variables, missing connections, etc.) |
113| `get_model_xml` | Preview the XMILE XML output |
114 
115## Example Usage
116 
117### Creating a simple population model
118 
119```
120User: Create a simple exponential growth model with a population starting at 100
121      and a growth rate of 0.1 per year
122 
123Claude: [Uses create_model, add_stock, add_aux, add_flow, add_connector, save_model]
124        Creates population_growth.stmx with:
125        - Stock: Population (initial=100)
126        - Aux: growth_rate (0.1)
127        - Flow: growth (Population * growth_rate) into Population
128```
129 
130### Reading and analyzing an existing model
131 
132```
133User: Read the carbon cycle model and explain what it does
134 
135Claude: [Uses read_model, list_variables]
136        This model has 3 stocks (Atmosphere, Land Biota, Soil) and 6 flows
137        representing carbon exchange through photosynthesis, respiration...
138```
139 
140### Building a biogeochemical model
141 
142```
143User: Create a two-box ocean model with surface and deep nutrients
144 
145Claude: [Uses create_model, add_stock (x4), add_aux (x8), add_flow (x6), save_model]
146        Creates a model with nutrient cycling between surface and deep ocean
147        including upwelling, downwelling, biological uptake, and remineralization
148```
149 
150## Validation
151 
152The `validate_model` tool checks for:
153 
154- **Undefined variables** - References to variables that don't exist
155- **Mass balance issues** - Stocks without flows, flows referencing non-existent stocks
156- **Missing connections** - Equations using variables without connectors (warning)
157- **Orphan flows** - Flows not connected to any stock
158- **Circular dependencies** - Infinite loops in auxiliary calculations
159 
160## XMILE Compatibility
161 
162- Output files use the [XMILE standard](https://docs.oasis-open.org/xmile/xmile/v1.0/xmile-v1.0.html)
163- Compatible with **Stella Professional 1.9+** and **Stella Architect**
164- Auto-layout positions elements reasonably; adjust manually in Stella if needed
165- Variable names with spaces are converted to underscores internally
166 
167## Project Structure
168 
169```
170stella-mcp/
171├── README.md
172├── LICENSE
173├── pyproject.toml
174└── stella_mcp/
175    ├── __init__.py
176    ├── server.py      # MCP server implementation
177    ├── xmile.py       # XMILE XML generation and parsing
178    └── validator.py   # Model validation logic
179```
180 
181## Contributing
182 
183Contributions are welcome! Please feel free to submit issues or pull requests.
184 
185## License
186 
187MIT License - see [LICENSE](LICENSE) for details.
188 
189## Acknowledgments
190 
191- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
192- [ISEE Systems](https://www.iseesystems.com/) for Stella and the XMILE format
193