Systems Modeling MCP server for AI agents

Systems-MCP is a server that enables interaction with the lethain:systems library for systems modeling through the Model Context Protocol (MCP). It provides tools to run systems models and load documentation into your context window, making it easier to create and visualize system simulations when working with Claude Desktop or similar AI assistants.

Installation

To install and set up Systems-MCP with Claude Desktop:

Ensure you have Claude Desktop installed on your computer

Clone the Systems-MCP repository:

git clone https://github.com/lethain/systems-mcp

Install uv if you don't already have it (required for running the MCP server). Follow the instructions at modelcontextprotocol.io/quickstart/server

Configure Claude Desktop to use the MCP server:

Open Claude Desktop and go to Settings > Developer
Have Claude create your MCP config file

Navigate to the config directory:

cd ~/Library/Application\ Support/Claude/

Edit the configuration file:
```
vi claude_desktop_config.json
```

Add the following configuration (replace the username with your own):

{
  "mcpServers": {
    "systems": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/systems-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Restart Claude Desktop for the changes to take effect

Using Systems-MCP

Systems-MCP provides two main tools for working with systems models:

Running a Systems Model

To run a systems model, use the run_systems_model tool. This tool takes two parameters:

The systems specification (required)
The number of simulation rounds to run (optional, defaults to 100)

Example usage in Claude:

Create your systems model specification

Ask Claude to run it using the MCP tool:

Please run this systems model using the run_systems_model tool:

{your systems specification here}

Loading Systems Documentation

To make it easier to create systems models, you can prime Claude's context window with documentation using the load_systems_documentation tool:

Ask Claude to load the documentation:

Please load the systems documentation using the load_systems_documentation tool

Once the documentation is loaded, you can ask Claude to help you create a systems model:
```
Can you help me create a systems model for {your scenario}?
```
After Claude generates a model specification, you can run it using the run_systems_model tool as described above

This approach is particularly useful when you're unfamiliar with the systems modeling syntax or want to explore different modeling approaches before implementing one.

Advanced Usage

You can combine these tools to create more complex workflows:

Load the documentation
Ask for help creating a model
Refine the model based on Claude's suggestions
Run the model to see the results
Make adjustments and run it again

This iterative process allows you to quickly develop and test systems models without needing to write code or understand the underlying implementation details.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "systems" '{"command":"uv","args":["--directory","/Users/will/systems-mcp","run","main.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "systems": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/will/systems-mcp",
                "run",
                "main.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "systems": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/will/systems-mcp",
                "run",
                "main.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect