OpenSWMM MCP Server

The OpenSWMM MCP Server exposes the OpenSWMM stormwater engine through the Model Context Protocol (MCP), allowing large-language models and AI assistants to open, run, query, and modify EPA-SWMM hydraulic and hydrologic models.

Built on FastMCP 3.x, the server provides 358 tools organised into 20 domain namespaces — including a 2D overland-flow surface namespace (twod_*) — nine swmm:// resources for structured data access, and seven guided-workflow prompts for common stormwater modelling tasks.

Getting Started

• Installation
  • From PyPI
  • From Source
  • With uv
  • With Claude Code
  • Requirements
  • Verifying the Installation
• Configuration
  • Environment Variables
  • Claude Code JSON Configuration
  • Transport Modes
  • Authentication (HTTP Transport)
• Quick Start
  • Prerequisites
  • Step 1: Open a Model
  • Step 2: Run the Simulation
  • Step 3: Query Results
  • Step 4: Close the Session
  • Next Steps

User Guide

• Tools
  • At a glance
  • Calling tools
  • Lifecycle (lifecycle_*)
  • Query (query_*)
  • Model (model_*)
  • Building (building_*)
  • Editing (editing_*)
  • Nodes (nodes_*)
  • Links (links_*)
  • Subcatchments (subcatchments_*)
  • Inflows (inflows_*)
  • Controls (controls_*)
  • Forcing (forcing_*)
  • Pollutants (pollutants_*)
  • Quality (quality_*)
  • Tables (tables_*)
  • Date/time (datetime_*)
  • Infrastructure (infrastructure_*)
  • Hot-start (hotstart_*)
  • Analysis (analysis_*)
  • Spatial (spatial_*)
  • GeoPackage (geopackage_*)
  • 2D Surface (twod_*)
  • See also
• Optimization with the gym_* tools
  • Concepts
  • Walkthrough: size two conduits to trade off flooding vs. peak outflow
  • Walkthrough: tune reactive control curves to trade off CSO vs. flooding
  • Tool reference
• Resources
  • URI Scheme
  • Available Resources
  • Using Resources
• Prompts
  • Available Prompts
• Examples
  • Example 1: Basic Simulation Workflow
  • Example 2: What-If Scenario Analysis
  • Example 3: Programmatic Model Building

Developer Guide

• Architecture
  • Overview
  • Server Composition via mount()
  • Lifespan and Session Lifecycle
  • Threading Model
  • Background Tasks
  • Error Handling
  • Authentication
  • Module Map
• Contributing
  • Development Setup
  • Project Layout
  • Coding Standards
  • Adding a New Tool
  • Running Tests
  • Linting
  • Building Documentation
  • Pull Request Process
  • Reporting Issues
• Testing
  • Test Layout
  • Mock Backend Pattern
  • In-Memory MCP Client
  • Running Unit Tests
  • Running Integration Tests
  • Test Configuration
  • Writing New Tests
  • Coverage Target
• Bundling skills with the MCP server
  • What a skill is (and what MCP is not)
  • Where skills live (canonical location)
  • Authoring a new skill
  • How skills are exposed over MCP
  • Native auto-discovery via a Claude Code / Cowork plugin
  • Summary
• Disposition of the alpha-RTC agent feedback (10 issues)
  • Summary
  • Implemented
  • Deferred (with rationale)
  • Incidental finding (not in the 10)

API Reference

• API Reference
  • Core Modules
  • Backend Modules
  • Utility Modules
  • Tool Modules
  • Resource Modules
  • Prompt Modules

Indices and tables

• Index

• Module Index

• Search Page