Installation

From PyPI

The simplest way to install the OpenSWMM MCP Server is via pip:

pip install openswmm.mcp

This installs the server and all required runtime dependencies (fastmcp, openswmm, pydantic, pydantic-settings, numpy).

From Source

Clone the repository and install in editable mode:

git clone https://github.com/HydroCouple/openswmm.mcp.git
cd openswmm.mcp
pip install -e ".[dev]"

The [dev] extra includes testing and linting tools (pytest, pytest-asyncio, pytest-cov, ruff).

With uv

If you use uv for fast Python package management:

uv pip install openswmm.mcp

Or for development:

uv pip install -e ".[dev]"

With Claude Code

The OpenSWMM MCP Server integrates directly with Claude Code as an MCP server. Add the following to your .claude/settings.json:

{
  "mcpServers": {
    "openswmm": {
      "command": "openswmm.mcp",
      "args": [],
      "env": {
        "OPENSWMM_MCP_WORKING_DIR": "/path/to/your/models"
      }
    }
  }
}

Alternatively, if you installed with uv and want to use the uvx runner:

{
  "mcpServers": {
    "openswmm": {
      "command": "uvx",
      "args": ["openswmm.mcp"],
      "env": {
        "OPENSWMM_MCP_WORKING_DIR": "/path/to/your/models"
      }
    }
  }
}

Requirements

• Python: 3.10 or later

• OpenSWMM Engine: openswmm>=6.0.0a1 (the compiled C engine bindings must be available for simulation features; the server can start without them but tools that call the engine will fail)

Verifying the Installation

After installing, verify that the server starts correctly:

python -m openswmm_mcp

This launches the server in stdio transport mode. Press Ctrl+C to stop it.

You can also check the installed version:

python -c "import openswmm_mcp; print(openswmm_mcp.__version__)"