COMSOL MCP Server

MCP Server for COMSOL Multiphysics simulation automation via AI agents.

English | 中文

Star History

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/Zhangyoupeng1996/Codex_MCP_Comsol.git
cd Codex_MCP_Comsol

# Install dependencies
python -m pip install -e .

# Test server
python -m src.server

Building PDF Knowledge Base

The pdf/ and knowledge_base/ directories are intentionally ignored by Git. Place your local COMSOL documentation PDFs under pdf/, then build the local knowledge base with the commands below.

# 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

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)

Tool	Description
comsol_start	Start local COMSOL client
comsol_connect	Connect to remote server
comsol_disconnect	Clear session
comsol_status	Get session info

Model (9)

Tool	Description
model_load	Load .mph file
model_create	Create empty model
model_save	Save to file
model_save_version	Save with timestamp
model_list	List loaded models
model_set_current	Set active model
model_clone	Clone model
model_remove	Remove from memory
model_inspect	Get model structure

Parameters (5)

Tool	Description
param_get	Get parameter value
param_set	Set parameter
param_list	List all parameters
param_sweep_setup	Setup parametric sweep
param_description	Get/set description

Geometry (14)

Tool	Description
geometry_list	List geometry sequences
geometry_create	Create geometry sequence
geometry_add_feature	Add generic feature
geometry_add_block	Add rectangular block
geometry_add_cylinder	Add cylinder
geometry_add_sphere	Add sphere
geometry_add_rectangle	Add 2D rectangle
geometry_add_circle	Add 2D circle
geometry_boolean_union	Union objects
geometry_boolean_difference	Subtract objects
geometry_import	Import CAD file
geometry_build	Build geometry
geometry_list_features	List features
geometry_get_boundaries	Get boundary numbers

Physics (16)

Tool	Description
physics_list	List physics interfaces
physics_get_available	Available physics types
physics_add	Add generic physics
physics_add_electrostatics	Add Electrostatics
physics_add_solid_mechanics	Add Solid Mechanics
physics_add_heat_transfer	Add Heat Transfer
physics_add_laminar_flow	Add Laminar Flow
physics_configure_boundary	Configure boundary condition
physics_set_material	Assign material
physics_list_features	List physics features
physics_remove	Remove physics
multiphysics_add	Add coupling
physics_interactive_setup_heat	Interactive heat BC setup
physics_setup_heat_boundaries	Configure heat boundaries
physics_interactive_setup_flow	Interactive flow BC setup
physics_boundary_selection	Generic boundary setup

Mesh (3)

Tool	Description
mesh_list	List mesh sequences
mesh_create	Generate mesh
mesh_info	Get mesh statistics

Study & Solving (8)

Tool	Description
study_list	List studies
study_solve	Solve synchronously
study_solve_async	Solve in background
study_get_progress	Get progress
study_cancel	Cancel solving
study_wait	Wait for completion
solutions_list	List solutions
datasets_list	List datasets

Results (9)

Tool	Description
results_evaluate	Evaluate expression
results_global_evaluate	Evaluate scalar
results_inner_values	Get time steps
results_outer_values	Get sweep values
results_export_data	Export data
results_export_image	Export plot image
results_exports_list	List export nodes
results_plots_list	List plot nodes

Knowledge (8)

Tool	Description
docs_get	Get documentation
docs_list	List available docs
physics_get_guide	Physics quick guide
troubleshoot	Troubleshooting help
modeling_best_practices	Best practices
pdf_search	Search PDF docs
pdf_search_status	PDF search status
pdf_list_modules	List PDF modules

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

Physics	Condition	Property
Heat Transfer	HeatFluxBoundary	q0
Heat Transfer	TemperatureBoundary	T0
Heat Transfer	ConvectiveHeatFlux	h, Text
Laminar Flow	InletBoundary	U0, NormalInflowVelocity
Laminar Flow	OutletBoundary	p0

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

Phase	Description	Status
1	Basic framework + Session + Model	Done
2	Parameters + Solving + Results	Done
3	Geometry + Physics + Mesh	Done
4	Embedded knowledge + Tool docs	Done
5	PDF vector retrieval	Done
6	Integration tests	In Progress

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

Resources

URI	Description
comsol://session/info	Session information
comsol://model/{name}/tree	Model tree structure
comsol://model/{name}/parameters	Model parameters
comsol://model/{name}/physics	Physics interfaces

License

MIT