Skip to content
BranchesTags
 
 

Repository files navigation

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/wjc9011/comsol-mcp.git
cd comsol-mcp

# Install dependencies
python -m pip install -e .

# Test server
python -m src.server

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

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)
│   │   ├── materials.py             # Material creation + property assignment
│   │   ├── 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 (5)

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

Use comsol_start_async(version="6.3") for slow first launches, then poll comsol_status until connected is true or startup.status is failed.

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 (15)

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/STL file, with STL mesh fallback
stl_analyze Inspect binary STL topology before import
geometry_build Build geometry
geometry_list_features List features
geometry_get_boundaries Get boundary numbers

Materials (1)

Tool Description
material_create Create material and set properties

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

Creating Aluminum Material

material_create(
    material_name="Aluminum",
    component_name="comp1",
    properties={
        "density": "2700[kg/m^3]",
        "youngsmodulus": "70e9[Pa]",
        "poissonsratio": "0.33",
        "thermalconductivity": "237[W/(m*K)]",
        "heatcapacity": "900[J/(kg*K)]",
    },
    domain_selection=[1],
)

Property names are COMSOL material property keys written to the selected material property group, def by default.

Mesh (4)

Tool Description
mesh_list List mesh sequences
mesh_create Generate mesh
mesh_info Get mesh statistics
mesh_import Import external mesh file such as STL

STL import notes

geometry_import now uses the COMSOL Java API directly instead of the higher level MPh path. For STL files, if solid geometry import fails during repair or geometry build, the tool automatically falls back to importing the STL into a mesh sequence and returns the original geometry error plus stl_analysis. STL mesh imports preserve imported domains by default and reset the component's default 3D view so the model opens centered in an isometric COMSOL-style view.

Use stl_analyze(file_path) before Boolean or CFD work. Non-manifold STL files can often be viewed and postprocessed as imported meshes, but they may need external repair before they can be converted into robust solids or subtracted from fluid domains.

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

About

No description, website, or topics provided.

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages