Aerobic Design MCP Server

Aerobic Design MCP Server

⚠️ DEVELOPMENT STATUS: This project is under active development and is not yet production-ready. APIs, interfaces, and functionality may change without notice. Use at your own risk for evaluation and testing purposes only. Not recommended for production deployments.

An intelligent MCP (Model Context Protocol) server for automated design of aerobic biological wastewater treatment systems with membrane bioreactor (MBR) technology.

Overview

The aerobic-design-mcp server enables AI-assisted wastewater treatment design through Claude AI. It implements sophisticated algorithms for flowsheet selection, reactor sizing, and mass balance calculations based on ASM2d (Activated Sludge Model 2d) kinetics.

Key Features

• Automated Flowsheet Selection: Chooses optimal process configuration (MLE, A2O, MLE+Post-Anoxic) based on effluent targets
• Rigorous Mass Balances: Temperature-corrected ASM2d kinetics with sludge, nitrogen, phosphorus, and oxygen balances
• MBR Integration: Membrane bioreactor sizing with flux constraints and fouling factors
• Deaeration Zone Sizing: Optional DO reduction before IR return to improve denitrification efficiency
• Dual MCP Architecture: FastMCP for design tools + Codex for ASM2d component fractionation
• State Persistence: JSON-based design state management for long workflows
• Report Generation: Markdown reports with Obsidian frontmatter, Mermaid diagrams, and LaTeX equations

Supported Flowsheet Types

Quick Start

Prerequisites

• Python 3.12+
• Claude Code (for MCP integration)
• Optional: QSDsan (for advanced simulations)

Installation

# Clone the repository
cd /path/to/mcp-servers/aerobic-design-mcp

# Install dependencies
pip install -r requirements.txt

# Optional: Install QSDsan
pip install qsdsan biosteam

MCP Configuration

Add to your Claude Code MCP configuration (.mcp.json):

{
  "mcpServers": {
    "aerobic-design": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/aerobic-design-mcp/server.py"],
      "env": {
        "MCP_TIMEOUT": "600000"
      }
    },
    "ASM2d-State-Variable-Estimator": {
      "type": "stdio",
      "command": "codex",
      "args": ["mcp"],
      "env": {
        "CODEX_HOME": "/path/to/aerobic-design-mcp/.codex"
      }
    }
  }
}

Basic Usage

Step 1: Collect Basis of Design

In Claude Code:

Please collect the basis of design for a wastewater treatment plant:
- Flow: 20,000 m3/d
- COD: 625 mg/L
- TKN: 62.5 mg/L
- TP: 9.37 mg/L
- TSS: 265 mg/L
- Temperature: 12-25°C
- Effluent targets: COD <50, TN <10, TP <1 mg/L

Step 2: Generate ASM2d State

Run the ASM2d state estimator to fractionate the wastewater components.

Step 3: Design the System

Design an aerobic MBR system for this wastewater.

Step 4: Generate Report

Generate a design report in Markdown format.

Design Workflow

1. collect_basis_of_design
   ├─ Flow rate, COD, nutrients, temperature
   └─ Effluent quality targets

2. ASM2d Estimator (Codex MCP)
   ├─ Component fractionation (25 mASM2d components)
   └─ Mass balance validation

3. validate_asm2d_state
   ├─ Load and enrich ASM2d state
   └─ Calculate rbCOD profile

4. design_aerobic_mbr
   ├─ Select optimal flowsheet
   ├─ Size reactor zones
   ├─ Calculate recycles
   └─ Validate compliance

5. generate_design_report
   └─ Markdown report (Obsidian-compatible)

MCP Tools

Core Tools

State Management

Validation

CLI Interface

For operations that may block the MCP server, use the CLI interface:

# Validate ASM2d state
python cli_runner.py validate --filepath asm2d_state.json

# Run complete design
python cli_runner.py design --params '{
  "auto_select": true