How do I use SWMM-MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SWMM-MCP Summarize the peak runoff and flooding results for the 'CityCenter' model." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

SWMM-MCP

MCP Toolbox for SWMM

Setup

Install uv
Clone this repository
Install dependencies with:

uv sync

Usage

Put the following json block into an MCP client (e.g. Claude Desktop). Though, some clients may have a different interface for configuring MCP servers. If you are currently in the root folder of this project in your IDE, you can find your full directory path by entering the command pwd.

{
  "mcpServers": {
    "SWMM": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/<path/to/directory>/SWMM-MCP",
        "server.py"
      ]
    }
  }
}

On Windows it may look something like this:

{
  "mcpServers": {
    "SWMM": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\Jacob\\Documents\\SWMM-MCP",
        "server.py"
      ]
    }
  }
}

Example system prompt if allowed by your client:

You are an expert SWMM (Storm Water Management Model) assistant. You have access to tools to inspect and analyze SWMM models. Use the available tools to answer questions accurately.

Inventory

Tools

Tool	Description
`list_models`	Returns a list of available models in the server.
`duplicate_model`	Duplicates a model and returns the new model name. Useful for testing scenarios.
`get_model_info`	Returns general information about a model.
`get_input_sections`	Returns a list of sections in the input file for a given model.
`get_input_info`	Returns the contents of a section of the input file for a given model.
`add_storage`	Replace a junction with a cylindrical storage node of specified volume.
`change_conduit`	Changes the diameter of a circular conduit in the model.
`run_model`	Runs a model.
`get_report_sections`	Returns a list of sections in the report file for a given model.
`get_report_info`	Returns the contents of a section of the report file for a given model.
`get_output_variables`	Returns a list of variables in the output file for a given model.
`get_output_objects`	Returns a list of objects in the output file for a given model and object type.
`change_storm`	Modify the model's storm event to an 24-hour SCS Type 2 design storm of a given depth.

Apps

App	Description
`prompt_model_upload`	Prompts the user with a UI where they can upload a SWMM model.
`plot_output_data`	Displays a full timeseries plot to the user.
`plot_model_map`	Creates an interactive map of the SWMM model and displays it to the user.
`plot_rainfall`	Displays a timeseries plot of the model's rainfall to the user.

Prompts

Name	Description
`list_models`	Which models are available?
`describe_model`	Tell me about the model.
`get_pipes_and_junctions`	How many pipes and junctions does it have?
`largest_pipe`	What's the largest pipe in the network?
`show_network`	Show me my network
`run_model`	Run a model for me
`compare_flow_largest_pipe`	Compare flow through the largest pipe for a 2-inch vs 4-inch storm.
`nodes_flood_4_inch`	Which nodes flood under a 4-inch storm?
`detention_recommendations`	Suggest detention locations to reduce downstream flooding.
`add_storage_and_rerun`	Add a storage unit at a node and rerun.
`node_flow_timeseries`	Show node flow during the simulation.
`compare_base_to_modified`	Compare base and modified scenarios.
`outfall_hydrograph_comparison`	Plot base vs. modified outfall hydrographs.

Troubleshooting

Adding server to client failure

For macOS users, you may run into an issue of the client being unable to find the path uv is installed. To resolve this issue, you can create a symlink to one of the paths the client already checks.

To first find where uv is installed, in your terminal run:

which uv

which will return something like: /Users/<user-name>/.local/bin/uv

Then, to create a symlink, in your terminal run:

sudo ln -s ~/.local/bin/uv /usr/local/bin/uv

where ~/.local/bin/uv is where uv is installed and /usr/local/bin/uv is part of the path your client checks. The error logs from the client should contain the paths it checks for uv.