Configuration#

The OpenSWMM MCP Server is configured through environment variables, all prefixed with OPENSWMM_MCP_. These can be set in your shell, in a .env file, or in the Claude Code MCP server configuration.

Environment Variables#

Variable	Type	Default	Description
`OPENSWMM_MCP_WORKING_DIR`	`str`	`"./"`	Base directory for model files and session working directories.
`OPENSWMM_MCP_MAX_SESSIONS`	`int`	`5`	Maximum number of concurrent simulation sessions.
`OPENSWMM_MCP_TRANSPORT`	`str`	`"stdio"`	Transport mode: `"stdio"`, `"http"`, or `"sse"`.
`OPENSWMM_MCP_HTTP_PORT`	`int`	`8080`	Port for HTTP/SSE transport (ignored for stdio).
`OPENSWMM_MCP_LOG_LEVEL`	`str`	`"INFO"`	Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`.
`OPENSWMM_MCP_OAUTH_ISSUER`	`str`	`None`	OAuth token issuer URL (HTTP transport only).
`OPENSWMM_MCP_OAUTH_AUDIENCE`	`str`	`None`	OAuth audience identifier (HTTP transport only).
`OPENSWMM_MCP_JWT_JWKS_URL`	`str`	`None`	JWKS endpoint for JWT verification (HTTP transport only).

Claude Code JSON Configuration#

When using the server with Claude Code, configure it in .claude/settings.json:

{
  "mcpServers": {
    "openswmm": {
      "command": "openswmm-mcp",
      "args": [],
      "env": {
        "OPENSWMM_MCP_WORKING_DIR": "/Users/me/swmm-models",
        "OPENSWMM_MCP_MAX_SESSIONS": "10",
        "OPENSWMM_MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Transport Modes#

stdio (default)#

The default transport mode. The server communicates over standard input/output and is intended for use with MCP clients like Claude Code that manage the server process directly. No authentication is required.

OPENSWMM_MCP_TRANSPORT=stdio openswmm-mcp

HTTP#

Runs the server as an HTTP endpoint with optional OAuth/JWT authentication. Suitable for multi-user or remote deployments.

OPENSWMM_MCP_TRANSPORT=http \
OPENSWMM_MCP_HTTP_PORT=8080 \
OPENSWMM_MCP_OAUTH_ISSUER=https://accounts.example.com \
OPENSWMM_MCP_OAUTH_AUDIENCE=openswmm-mcp \
OPENSWMM_MCP_JWT_JWKS_URL=https://accounts.example.com/.well-known/jwks.json \
openswmm-mcp

SSE (Server-Sent Events)#

Similar to HTTP but uses Server-Sent Events for streaming progress updates. Useful for browser-based clients.

OPENSWMM_MCP_TRANSPORT=sse \
OPENSWMM_MCP_HTTP_PORT=8080 \
openswmm-mcp

Authentication (HTTP Transport)#

When the transport is set to http or sse, the server supports two authentication methods:

OAuth: For interactive users authenticating through a browser-based flow. Configure OPENSWMM_MCP_OAUTH_ISSUER and OPENSWMM_MCP_OAUTH_AUDIENCE.
JWT: For service-to-service authentication (API keys, CI/CD pipelines). Configure OPENSWMM_MCP_JWT_JWKS_URL and OPENSWMM_MCP_OAUTH_AUDIENCE.

Both methods can be active simultaneously. When using stdio transport, authentication is bypassed entirely.