COMSOL MCP Server

MCP Server for COMSOL Multiphysics simulation automation via AI agents.

English | 中文

Project Goal

Build a complete COMSOL MCP Server enabling AI agents (like Claude, opencode) to perform multiphysics simulations through the MCP protocol:

1. Model Management - Create, load, save, version control
2. Geometry Building - Blocks, cylinders, spheres, boolean operations
3. Physics Configuration - Heat transfer, fluid flow, electrostatics, solid mechanics
4. Meshing & Solving - Auto mesh, stationary/time-dependent studies
5. Results Visualization - Evaluate expressions, export plots
6. Knowledge Integration - Embedded guides + PDF semantic search

Requirements

• COMSOL Multiphysics (version 5.x or 6.x)
• Python 3.10+ (NOT Windows Store version)
• Java runtime (required by MPh/COMSOL)

Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/comsol-mcp.git
cd comsol-mcp

# Install dependencies
python -m pip install -e .

# Test server
python -m src.server

Usage

Option 1: With opencode

Create opencode.json in project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "comsol": {
      "type": "local",
      "command": ["python", "-m", "src.server"],
      "enabled": true,
      "environment": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      },
      "timeout": 30000
    }
  }
}

Option 2: With Claude Desktop

{
  "mcpServers": {
    "comsol": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/comsol-mcp"
    }
  }
}

Code Structure

comsol_mcp/
├── opencode.json                    # MCP server config for opencode
├── pyproject.toml                   # Python project config
├── README.md                        # This file
│
├── src/
│   ├── server.py                    # MCP Server entry point
│   ├── tools/
│   │   ├── session.py               # COMSOL session management (start/stop/status)
│   │   ├── model.py                 # Model CRUD + versioning
│   │   ├── parameters.py            # Parameter management + sweeps
│   │   ├── geometry.py              # Geometry creation (block/cylinder/sphere)
│   │   ├── physics.py               # Physics interfaces + boundary conditions
│   │   ├── mesh.py                  # Mesh generation
│   │   ├── study.py                 # Study creation + solving (sync/async)
│   │   └── results.py               # Results evaluation + export
│   ├── resources/
│   │   └── model_resources.py       # MCP resources (model tree, parameters)
│   ├── knowledge/
│   │   ├── embedded.py              # Embedded physics guides + troubleshooting
│   │   ├── retriever.py             # PDF vector search retriever
│   │   └── pdf_processor.py         # PDF chunking + embedding
│   ├── async_handler/
│   │   └── solver.py                # Async solving with progress tracking
│   └── utils/
│       └── versioning.py            # Model version path management
│
├── scripts/
│   └── build_knowledge_base.py      # Build PDF vector database
│
├── client_script/                   # Standalone modeling scripts (examples)
│   ├── create_chip_tsv_final.py     # Example: Chip thermal model
│   ├── create_micromixer_auto.py    # Example: Fluid flow simulation
│   ├── create_chip_thermal*.py      # Various chip thermal variants
│   ├── create_micromixer*.py        # Various micromixer variants
│   ├── visualize_*.py               # Result visualization scripts
│   ├── add_visualization.py         # Add plot groups to model
│   └── test_*.py                    # Integration tests
│
├── comsol_models/                   # Saved models (structured)
│   ├── chip_tsv_thermal/
│   │   ├── chip_tsv_thermal_20260216_*.mph
│   │   └── chip_tsv_thermal_latest.mph
│   └── micromixer/
│       └── micromixer_*.mph
│
└── tests/
    └── test_basic.py                # Unit tests

Available Tools (80+ total)

Session (4)

Model (9)

Parameters (5)

Geometry (14)

Physics (16)

Mesh (3)

Study & Solving (8)

Results (9)

Knowledge (8)

Example Cases

Case 1: Chip Thermal Model with TSV

3D thermal analysis of a silicon chip with Through-Silicon Via (TSV).

Geometry: 60×60×5 µm chip, 5 µm diameter TSV hole, 10×10 µm heat source

# Key steps:
# 1. Create chip block and TSV cylinder
# 2. Boolean difference (subtract TSV from chip)
# 3. Add Silicon material (k=130 W/m·K)
# 4. Add Heat Transfer physics
# 5. Set heat flux on top, temperature on bottom
# 6. Solve and evaluate temperature distribution

Script: client_script/create_chip_tsv_final.py

Run:

cd /path/to/comsol-mcp
python client_script/create_chip_tsv_final.py

Results: Temperature rise from ambient with heat flux of 1 MW/m²

Case 2: Micromixer Fluid Flow

3D laminar flow simulation in a microfluidic channel.

Geometry: 600×100×50 µm rectangular channel

# Key steps:
# 1. Create rectangular channel block
# 2. Add water material (ρ=1000 kg/m³, μ=0.001 Pa·s)
# 3. Add Laminar Flow physics
# 4. Set inlet velocity (1 mm/s), outlet pressure
# 5. Add Transport of Diluted Species for mixing
# 6. Solve and evaluate velocity profile

Script: client_script/create_micromixer_auto.py

Run:

cd /path/to/comsol-mcp
python client_script/create_micromixer_auto.py

Results: Velocity distribution, concentration mixing profile

Model Versioning

Models are saved with structured paths:

./comsol_models/{model_name}/{model_name}_{timestamp}.mph
./comsol_models/{model_name}/{model_name}_latest.mph

Example:

./comsol_models/chip_tsv_thermal/chip_tsv_thermal_20260216_140514.mph
./comsol_models/chip_tsv_thermal/chip_tsv_thermal_latest.mph

Key Technical Discoveries

1. mph Library API Patterns

# Access Java model via property (not callable)
jm = model.java  # NOT model.java()

# Create component with True flag
comp = jm.component().create('comp1', True)

# Create 3D geometry
geom = comp.geom().create('geom1', 3)

# Create physics with geometry reference
physics = comp.physics().create('spf', 'LaminarFlow', 'geom1')

# Boundary condition with selection
bc = physics.create('inl1', 'InletBoundary')
bc.selection().set([1, 2, 3])
bc.set('U0', '1[mm/s]')

2. Boundary Condition Property Names

3. Client Session Limitation

The mph library creates a singleton COMSOL client. Only one Client can exist per Python process:

# This is handled in session.py - client is kept alive and models are cleared
client.clear()  # Clear models instead of full disconnect

4. Offline Embedding Model

PDF search supports offline operation with local HuggingFace cache:

# Set mirror for China
export HF_ENDPOINT=https://hf-mirror.com

Development Status

Next Steps

1. Complete Phase 6 - Full integration test with proper boundary conditions
2. Visualization Export - Generate PNG images from plot groups
3. LSP Warnings - Fix type hints in physics.py
4. More Examples - Add electrostatics, solid mechanics cases
5. Error Handling - Improve error messages and recovery

Building PDF Knowledge Base

# Install additional dependencies
pip install pymupdf chromadb sentence-transformers

# Build knowledge base
python scripts/build_knowledge_base.py

# Check status
python scripts/build_knowledge_base.py --status

Resources

License

MIT