Skip to content
Back to search

COMSOL_Multiphysics_MCP

MCP Server for COMSOL Multiphysics simulation automation via AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wjc9011--comsol-multiphysics-mcp/badge.svg)](/listings/wjc9011--comsol-multiphysics-mcp)

HTML

<a href="/listings/wjc9011--comsol-multiphysics-mcp"><img src="/api/listings/wjc9011--comsol-multiphysics-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Clone repository
git clone https://github.com/wjc9011/COMSOL_Multiphysics_MCP.git
cd COMSOL_Multiphysics_MCP

# Install dependencies
python -m pip install -e .

# Test server
python -m src.server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 500 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # COMSOL MCP Server
  2. MCP Server for COMSOL Multiphysics simulation automation via AI agents.
  3. English | [中文](README_CN.md)
  4. ## Star History
  5. [![GitHub stars](https://img.shields.io/github/stars/wjc9011/COMSOL_Multiphysics_MCP?style=social)](https://github.com/wjc9011/COMSOL_Multiphysics_MCP/stargazers)
  6. [![Star History Chart](https://starchart.cc/wjc9011/COMSOL_Multiphysics_MCP.svg)](https://starchart.cc/wjc9011/COMSOL_Multiphysics_MCP)
  7. ## Publication and Citation
  8. The research paper describing COMSOL-MCP is available in *Neurocomputing*:
  9. > Naiyin Zhang and Junchao Wang, “[COMSOL-MCP: An open-source model context protocol interface for AI-assisted multiphysics simulation](https://doi.org/10.1016/j.neucom.2026.134481),” *Neurocomputing*, vol. 703, article 134481, 2026.
  10. Publisher page: [ScienceDirect](https://linkinghub.elsevier.com/retrieve/pii/S0925231226018795)
  11. If COMSOL-MCP contributes to your research, please cite the paper:
  12. ```bibtex
  13. @article{Zhang2026COMSOLMCP,
  14. title = {COMSOL-MCP: An Open-Source Model Context Protocol Interface for AI-Assisted Multiphysics Simulation},
  15. author = {Zhang, Naiyin and Wang, Junchao},
  16. journal = {Neurocomputing},
  17. volume = {703},
  18. pages = {134481},
  19. year = {2026},
  20. doi = {10.1016/j.neucom.2026.134481},
  21. url = {https://doi.org/10.1016/j.neucom.2026.134481}
  22. }
  23. ```
  24. ### Citation guidance
  25. - Cite the paper when referring to the COMSOL-MCP method, architecture, capabilities, or evaluation.
  26. - If you use or modify the software, cite both the paper and the repository. Use GitHub’s **Cite this repository** menu, which is backed by [`CITATION.cff`](CITATION.cff).
  27. - For reproducibility, identify the exact release tag or commit used and include the repository URL and access date in your data/code availability statement.
  28. ## Project Goal
  29. Build a complete COMSOL MCP Server enabling AI agents (like Claude, opencode) to perform multiphysics simulations through the MCP protocol:
  30. 1. **Model Management** - Create, load, save, version control
  31. 2. **Geometry Building** - Blocks, cylinders, spheres, boolean operations
  32. 3. **Physics Configuration** - Heat transfer, fluid flow, electrostatics, solid mechanics
  33. 4. **Meshing & Solving** - Auto mesh, stationary/time-dependent studies
  34. 5. **Results Visualization** - Evaluate expressions, export plots
  35. 6. **Knowledge Integration** - Embedded guides + PDF semantic search
  36. ## Requirements
  37. - **COMSOL Multiphysics** (version 5.x or 6.x)
  38. - **Python 3.10+** (NOT Windows Store version)
  39. - **Java runtime** (required by MPh/COMSOL)
  40. ## Installation
  41. ```bash
  42. # Clone repository
  43. git clone https://github.com/wjc9011/COMSOL_Multiphysics_MCP.git
  44. cd COMSOL_Multiphysics_MCP
  45. # Install dependencies
  46. python -m pip install -e .
  47. # Test server
  48. python -m src.server
  49. ```
  50. ## Building PDF Knowledge Base
  51. ```bash
  52. # Install additional dependencies
  53. pip install pymupdf chromadb sentence-transformers
  54. # Build knowledge base
  55. python scripts/build_knowledge_base.py
  56. # Check status
  57. python scripts/build_knowledge_base.py --status
  58. ```
  59. ## Usage
  60. ### Option 1: With opencode
  61. Create `opencode.json` in project root:
  62. ```json
  63. {
  64. "$schema": "https://opencode.ai/config.json",
  65. "mcp": {
  66. "comsol": {
  67. "type": "local",
  68. "command": ["python", "-m", "src.server"],
  69. "enabled": true,
  70. "environment": {
  71. "HF_ENDPOINT": "https://hf-mirror.com"
  72. },
  73. "timeout": 30000
  74. }
  75. }
  76. }
  77. ```
  78. ### Option 2: With Claude Desktop
  79. ```json
  80. {
  81. "mcpServers": {
  82. "comsol": {
  83. "command": "python",
  84. "args": ["-m", "src.server"],
  85. "cwd": "/path/to/COMSOL_Multiphysics_MCP"
  86. }
  87. }
  88. }
  89. ```
  90. ## Code Structure
  91. ```
  92. comsol_mcp/
  93. ├── opencode.json # MCP server config for opencode
  94. ├── pyproject.toml # Python project config
  95. ├── README.md # This file
  96. │
  97. ├── src/
  98. │ ├── server.py # MCP Server entry point
  99. │ ├── tools/
  100. │ │ ├── session.py # COMSOL session management (start/stop/status)
  101. │ │ ├── model.py # Model CRUD + versioning
  102. │ │ ├── parameters.py # Parameter management + sweeps
  103. │ │ ├── geometry.py # Geometry creation (block/cylinder/sphere)
  104. │ │ ├── physics.py # Physics interfaces + boundary conditions
  105. │ │ ├── mesh.py # Mesh generation
  106. │ │ ├── study.py # Study creation + solving (sync/async)
  107. │ │ └── results.py # Results evaluation + export
  108. │ ├── resources/
  109. │ │ └── model_resources.py # MCP resources (model tree, parameters)
  110. │ ├── knowledge/
  111. │ │ ├── embedded.py # Embedded physics guides + troubleshooting
  112. │ │ ├── retriever.py # PDF vector search retriever
  113. │ │ └── pdf_processor.py # PDF chunking + embedding
  114. │ ├── async_handler/
  115. │ │ └── solver.py # Async solving with progress tracking
  116. │ └── utils/
  117. │ └── versioning.py # Model version path management
  118. │
  119. ├── scripts/
  120. │ └── build_knowledge_base.py # Build PDF vector database
  121. │
  122. ├── client_script/ # Standalone modeling scripts (examples)
  123. │ ├── create_chip_tsv_final.py # Example: Chip thermal model
  124. │ ├── create_micromixer_auto.py # Example: Fluid flow simulation
  125. │ ├── create_chip_thermal*.py # Various chip thermal variants
  126. │ ├── create_micromixer*.py # Various micromixer variants
  127. │ ├── visualize_*.py # Result visualization scripts
  128. │ ├── add_visualization.py # Add plot groups to model
  129. │ └── test_*.py # Integration tests
  130. │
  131. ├── comsol_models/ # Saved models (structured)
  132. │ ├── chip_tsv_thermal/
  133. │ │ ├── chip_tsv_thermal_20260216_*.mph
  134. │ │ └── chip_tsv_thermal_latest.mph
  135. │ └── micromixer/
  136. │ └── micromixer_*.mph
  137. │
  138. └── tests/
  139. └── test_basic.py # Unit tests
  140. ```
  141. ## Available Tools (100+ total)
  142. ### Session (4)
  143. | Tool | Description |
  144. |------|-------------|
  145. | `comsol_start` | Start local COMSOL client |
  146. | `comsol_connect` | Connect to remote server |
  147. | `comsol_disconnect` | Clear session |
  148. | `comsol_status` | Get session info |
  149. ### Model (9)
  150. | Tool | Description |
  151. |------|-------------|
  152. | `model_load` | Load .mph file |
  153. | `model_create` | Create empty model |
  154. | `model_save` | Save to file |
  155. | `model_save_version` | Save with timestamp |
  156. | `model_list` | List loaded models |
  157. | `model_set_current` | Set active model |
  158. | `model_clone` | Clone model |
  159. | `model_remove` | Remove from memory |
  160. | `model_inspect` | Get model structure |
  161. ### Parameters (5)
  162. | Tool | Description |
  163. |------|-------------|
  164. | `param_get` | Get parameter value |
  165. | `param_set` | Set parameter |
  166. | `param_list` | List all parameters |
  167. | `param_sweep_setup` | Setup parametric sweep |
  168. | `param_description` | Get/set description |
  169. ### Geometry (16)
  170. | Tool | Description |
  171. |------|-------------|
  172. | `geometry_list` | List geometry sequences |
  173. | `geometry_create` | Create geometry sequence |
  174. | `geometry_add_feature` | Add generic feature |
  175. | `geometry_add_block` | Add rectangular block |
  176. | `geometry_add_cylinder` | Add cylinder |
  177. | `geometry_add_sphere` | Add sphere |
  178. | `geometry_add_rectangle` | Add 2D rectangle |
  179. | `geometry_add_circle` | Add 2D circle |
  180. | `geometry_boolean_union` | Union objects |
  181. | `geometry_boolean_difference` | Subtract objects |
  182. | `geometry_import` | Import CAD file |
  183. | `geometry_build` | Build geometry |
  184. | `geometry_list_features` | List features |
  185. | `geometry_get_boundaries` | Get boundary numbers |
  186. | `geometry_create_box_selection` | Create a named selection by position |
  187. | `geometry_create_side_selections` | Create left/right/top/bottom selections |
  188. ### Physics (28)
  189. | Tool | Description |
  190. |------|-------------|
  191. | `physics_list` | List physics interfaces |
  192. | `physics_get_available` | Available physics types |
  193. | `physics_add` | Add generic physics |
  194. | `physics_add_electrostatics` | Add Electrostatics |
  195. | `physics_add_solid_mechanics` | Add Solid Mechanics |
  196. | `physics_add_heat_transfer` | Add Heat Transfer |
  197. | `physics_add_laminar_flow` | Add Laminar Flow |
  198. | `physics_add_acoustics` | Add a geometry-based acoustic interface by COMSOL type |
  199. | `physics_add_pressure_acoustics` | Add Pressure Acoustics |
  200. | `physics_add_coefficient_form_pde` | Add Coefficient Form PDE |
  201. | `physics_add_general_form_pde` | Add General Form PDE |
  202. | `physics_add_weak_form_pde` | Add Weak Form PDE |
  203. | `physics_configure_boundary` | Configure boundary condition |
  204. | `physics_configure_acoustic_boundary` | Configure one acoustic boundary condition |
  205. | `physics_setup_acoustic_boundaries` | Configure multiple acoustic boundary conditions |
  206. | `physics_configure_pde_boundary` | Configure one PDE boundary condition |
  207. | `physics_setup_pde_boundaries` | Configure multiple PDE boundary conditions |
  208. | `physics_get_acoustic_boundary_conditions` | List common acoustic boundary feature types |
  209. | `physics_get_pde_boundary_conditions` | List common PDE boundary feature types |
  210. | `physics_set_material` | Assign material |
  211. | `physics_list_features` | List physics features |
  212. | `physics_remove` | Remove physics |
  213. | `multiphysics_add` | Add coupling |
  214. | `physics_interactive_setup_heat` | Interactive heat BC setup |
  215. | `physics_setup_heat_boundaries` | Configure heat boundaries |
  216. | `physics_interactive_setup_flow` | Interactive flow BC setup |
  217. | `physics_boundary_selection` | Generic boundary setup |
  218. ### Electrochemistry (10)
  219. Battery, fuel cell, electrodeposition, and corrosion support backed by a type
  220. registry **verified against a live COMSOL 6.3 session** (26 interfaces, 600+
  221. feature/subfeature types). A complete worked example — an 18650 cell 1C
  222. constant-current discharge — is included in
  223. `src/knowledge/prompts/electrochemistry.md`; call `docs_get("electrochemistry")`
  224. to retrieve it at runtime.
  225. | Tool | Description |
  226. |------|-------------|
  227. | `electrochemistry_get_interfaces` | List verified interface types (battery, current distribution, corrosion, ...) |
  228. | `electrochemistry_get_feature_types` | List verified feature types of an interface with dimensions |
  229. | `electrochemistry_add_interface` | Add a verified interface (e.g. `LithiumIonBatteryMPH`, `LumpedBattery`) |
  230. | `electrochemistry_list_features` | Inspect features with actual COMSOL types (`getType()`) |
  231. | `electrochemistry_add_feature` | Create a feature, incl. subfeatures via `parent_feature` |
  232. | `electrochemistry_set_feature_selection` | Assign domains/boundaries to an existing feature |
  233. | `electrochemistry_set_feature_properties` | Set feature properties (rejected names reported) |
  234. | `electrochemistry_list_feature_properties` | Ask COMSOL for a feature's valid property names |
  235. | `electrochemistry_list_interface_properties` | Read interface-level property groups (e.g. `BatterySettings`) |
  236. | `electrochemistry_set_interface_properties` | Configure interface-level settings (capacity, SOC, current, ...) |
  237. ### Mesh (4)
  238. | Tool | Description |
  239. |------|-------------|
  240. | `mesh_list` | List mesh sequences |
  241. | `mesh_create_sequence` | Create a mesh sequence |
  242. | `mesh_create` | Generate mesh |
  243. | `mesh_info` | Get mesh statistics |
  244. ### Study & Solving (8)
  245. | Tool | Description |
  246. |------|-------------|
  247. | `study_list` | List studies |
  248. | `study_solve` | Solve synchronously |
  249. | `study_solve_async` | Solve in background |
  250. | `study_get_progress` | Get progress |
  251. | `study_cancel` | Cancel solving |
  252. | `study_wait` | Wait for completion |
  253. | `solutions_list` | List solutions |
  254. | `datasets_list` | List datasets |
  255. ### Results (9)
  256. | Tool | Description |
  257. |------|-------------|
  258. | `results_evaluate` | Evaluate expression |
  259. | `results_global_evaluate` | Evaluate scalar |
  260. | `results_inner_values` | Get time steps |
  261. | `results_outer_values` | Get sweep values |
  262. | `results_export_data` | Export data |
  263. | `results_export_image` | Export plot image |
  264. | `results_exports_list` | List export nodes |
  265. | `results_plots_list` | List plot nodes |
  266. ### Knowledge (8)
  267. | Tool | Description |
  268. |------|-------------|
  269. | `docs_get` | Get documentation |
  270. | `docs_list` | List available docs |
  271. | `physics_get_guide` | Physics quick guide |
  272. | `troubleshoot` | Troubleshooting help |
  273. | `modeling_best_practices` | Best practices |
  274. | `pdf_search` | Search PDF docs |
  275. | `pdf_search_status` | PDF search status |
  276. | `pdf_list_modules` | List PDF modules |
  277. ## Example Cases
  278. ### Case 1: Chip Thermal Model with TSV
  279. 3D thermal analysis of a silicon chip with Through-Silicon Via (TSV).
  280. **Geometry**: 60×60×5 µm chip, 5 µm diameter TSV hole, 10×10 µm heat source
  281. ```python
  282. # Key steps:
  283. # 1. Create chip block and TSV cylinder
  284. # 2. Boolean difference (subtract TSV from chip)
  285. # 3. Add Silicon material (k=130 W/m·K)
  286. # 4. Add Heat Transfer physics
  287. # 5. Set heat flux on top, temperature on bottom
  288. # 6. Solve and evaluate temperature distribution
  289. ```
  290. **Script**: `client_script/create_chip_tsv_final.py`
  291. **Run**:
  292. ```bash
  293. cd /path/to/COMSOL_Multiphysics_MCP
  294. python client_script/create_chip_tsv_final.py
  295. ```
  296. **Results**: Temperature rise from ambient with heat flux of 1 MW/m²
  297. ### Case 2: Micromixer Fluid Flow
  298. 3D laminar flow simulation in a microfluidic channel.
  299. **Geometry**: 600×100×50 µm rectangular channel
  300. ```python
  301. # Key steps:
  302. # 1. Create rectangular channel block
  303. # 2. Add water material (ρ=1000 kg/m³, μ=0.001 Pa·s)
  304. # 3. Add Laminar Flow physics
  305. # 4. Set inlet velocity (1 mm/s), outlet pressure
  306. # 5. Add Transport of Diluted Species for mixing
  307. # 6. Solve and evaluate velocity profile
  308. ```
  309. **Script**: `client_script/create_micromixer_auto.py`
  310. **Run**:
  311. ```bash
  312. cd /path/to/COMSOL_Multiphysics_MCP
  313. python client_script/create_micromixer_auto.py
  314. ```
  315. **Results**: Velocity distribution, concentration mixing profile
  316. ## Model Versioning
  317. Models are saved with structured paths:
  318. ```
  319. ./comsol_models/{model_name}/{model_name}_{timestamp}.mph
  320. ./comsol_models/{model_name}/{model_name}_latest.mph
  321. ```
  322. Example:
  323. ```
  324. ./comsol_models/chip_tsv_thermal/chip_tsv_thermal_20260216_140514.mph
  325. ./comsol_models/chip_tsv_thermal/chip_tsv_thermal_latest.mph
  326. ```
  327. ## Key Technical Discoveries
  328. ### 1. mph Library API Patterns
  329. ```python
  330. # Access Java model via property (not callable)
  331. jm = model.java # NOT model.java()
  332. # Create component with True flag
  333. comp = jm.component().create('comp1', True)
  334. # Create 3D geometry
  335. geom = comp.geom().create('geom1', 3)
  336. # Create physics with geometry reference
  337. physics = comp.physics().create('spf', 'LaminarFlow', 'geom1')
  338. # Boundary condition with selection
  339. bc = physics.create('inl1', 'InletBoundary')
  340. bc.selection().set([1, 2, 3])
  341. bc.set('U0', '1[mm/s]')
  342. ```
  343. ### 2. Boundary Condition Property Names
  344. | Physics | Condition | Property |
  345. |---------|-----------|----------|
  346. | Heat Transfer | HeatFluxBoundary | `q0` |
  347. | Heat Transfer | TemperatureBoundary | `T0` |
  348. | Heat Transfer | ConvectiveHeatFlux | `h`, `Text` |
  349. | Laminar Flow | InletBoundary | `U0`, `NormalInflowVelocity` |
  350. | Laminar Flow | OutletBoundary | `p0` |
  351. | Pressure Acoustics | SoundHard | No additional property |
  352. | Pressure Acoustics | SoundSoft | No additional property |
  353. | Pressure Acoustics | Pressure | `p0` |
  354. | Pressure Acoustics | Impedance | `Zn` |
  355. | Pressure Acoustics | NormalAcceleration | `nacc` |
  356. | Pressure Acoustics | NormalVelocity | `nvel` |
  357. | Pressure Acoustics | PlaneWaveRadiation | No additional property |
  358. | Pressure Acoustics | SphericalWaveRadiation | No additional property |
  359. | PDE | DirichletBoundary | `r` |
  360. | PDE | FluxBoundary | `g`, `q` |
  361. | PDE | ZeroFluxBoundary | No additional property |
  362. | PDE | WeakContribution | `weak` |
  363. | PDE | PeriodicCondition | No additional property |
  364. ### 3. Client Session Limitation
  365. The mph library creates a singleton COMSOL client. Only one Client can exist per Python process:
  366. ```python
  367. # This is handled in session.py - client is kept alive and models are cleared
  368. client.clear() # Clear models instead of full disconnect
  369. ```
  370. ### 4. Offline Embedding Model
  371. PDF search supports offline operation with local HuggingFace cache:
  372. ```bash
  373. # Set mirror for China
  374. export HF_ENDPOINT=https://hf-mirror.com
  375. ```
  376. ## Development Status
  377. | Phase | Description | Status |
  378. |-------|-------------|--------|
  379. | 1 | Basic framework + Session + Model | Done |
  380. | 2 | Parameters + Solving + Results | Done |
  381. | 3 | Geometry + Physics + Mesh | Done |
  382. | 4 | Embedded knowledge + Tool docs | Done |
  383. | 5 | PDF vector retrieval | Done |
  384. | 6 | Integration tests | In Progress |
  385. ## Next Steps
  386. 1. **Complete Phase 6** - Full integration test with proper boundary conditions
  387. 2. **Visualization Export** - Generate PNG images from plot groups
  388. 3. **LSP Warnings** - Fix type hints in physics.py
  389. 4. **More Examples** - Add electrostatics, solid mechanics cases
  390. 5. **Error Handling** - Improve error messages and recovery
  391. ## Resources
  392. | URI | Description |
  393. |-----|-------------|
  394. | `comsol://session/info` | Session information |
  395. | `comsol://model/{name}/tree` | Model tree structure |
  396. | `comsol://model/{name}/parameters` | Model parameters |
  397. | `comsol://model/{name}/physics` | Physics interfaces |
  398. ## License
  399. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.