COMSOL MCP Server

MCP Server for COMSOL Multiphysics simulation automation via AI agents.

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/HBPEKING-TKS/mcp_server.git
cd comsol-multiphysics-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 (requires COMSOL PDF documentation)
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-multiphysics-mcp"
    }
  }
}

Code Structure

comsol-multiphysics-mcp/
├── opencode.json                    # MCP server config for opencode
├── pyproject.toml                   # Python project config
├── README.md                        # This file
├── LICENSE                          # MIT License
│
├── 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
│   │   └── prompts/                 # Reference docs (API, physics, workflow)
│   ├── 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
│
├── comsol_models/                   # Saved models (structured)
│   └── {model_name}/
│       ├── {model_name}_{timestamp}.mph
│       └── {model_name}_latest.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_block	Add rectangular block
geometry_add_cylinder	Add cylinder
geometry_add_sphere	Add sphere
geometry_boolean_union	Union objects
geometry_boolean_difference	Subtract objects
geometry_import	Import CAD file
geometry_build	Build geometry
...	...

Physics (16)

Tool	Description
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
multiphysics_add	Add coupling
physics_setup_heat_boundaries	Configure heat boundaries
physics_setup_flow_boundaries	Configure flow boundaries
...	...

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

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

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

Key Technical Discoveries

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)

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

Boundary Condition Property Names

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

Model Versioning

Models are saved with structured paths:

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

MCP 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