Systems MCP
# systems-mcp
[systems-mcp](https://github.com/lethain/systems-mcp) is an MCP server for interacting with
the [`lethain:systems`](https://github.com/lethain/systems/) library for systems modeling.
It provides two tools:
* `run_systems_model` runs the `systems` specification of a systems model.
Takes two parameters, the specification and, optionally, the number of
rounds to run the model (defaulting to 100).
* `load_systems_documentation` loads documentation and examples into the context window.
This is useful for priming models to be more helpful at writing systems models.
It is intended for running locally in conjunction with Claude Desktop or a similar tool.
## Usage
Here's an example of using `systems-mcp` to run and render a model.
Here is the artifact generated from that prompt, including the output from
running the systems model.
Finally, here is an example of using the `load_systems_documentation` tool to prime
the context window and using it to help generate a systems specification.
This is loosely equivalent to including [`lethain:systems/README.md`](https://raw.githubusercontent.com/lethain/systems/refs/heads/master/README.md) in the context window,
but also includes a handful of additional examples
(see the included files in [./docs/](./docs/).
Then you can render the model as before.
The most interesting piece here is that I've never personally used `systems` to model a social network,
but the LLM was able to do a remarkably decent job at generating a specification despite that.
## Installation
These instructions describe installation for [Claude Desktop](https://claude.ai/download) on OS X.
It should work similarly on other platforms.
1. Install [Claude Desktop](https://claude.ai/download).
2. Clone [systems-mcp](https://github.com/lethain/systems-mcp) into
a convenient location, I'm assuming `/Users/will/systems-mcp`
3. Make sure you have `uv` installed, you can [follow these instructions](https://modelcontextprotocol.io/quickstart/server)
4. Go to Cladue Desktop, Setting, Developer, and have it create your MCP config file.
Then you want to update your `claude_desktop_config.json`.
(Note that you should replace `will` with your user, e.g. the output of `whoami`.
cd ~/Library/Application\ Support/Claude/
vi claude_desktop_config.json
Then add this section:
{
"mcpServers": {
"systems": {
"command": "uv",
"args": [
"--directory",
"/Users/will/systems-mcp",
"run",
"main.py"
]
}
}
}
5. Close Claude and reopen it.
6. It should work...
TDQS
Scored across 2 tools
The two tools have completely distinct purposes: one loads documentation/examples for reference, while the other executes a model with given specifications. There is no overlap in functionality, and an agent would easily differentiate between them based on their clear descriptions.
Both tools follow a consistent verb_noun pattern with snake_case naming: load_systems_documentation and run_systems_model. The naming is predictable and readable, with no deviations in style or convention across the set.
With only 2 tools, the server feels thin for the domain of 'systems modeling,' which typically involves more operations like creating, updating, or analyzing models. This limited set may hinder agents from performing comprehensive tasks, as it lacks tools for specification generation, validation, or result analysis beyond basic execution.
The tool set is severely incomplete for systems modeling. It provides documentation loading and model execution but misses essential operations such as creating or editing specifications, validating models, analyzing outputs in-depth, or managing model versions. This creates significant gaps that will likely cause agent failures in real-world scenarios.