COMSOL Multiphysics MCP

COMSOL Multiphysics MCP is a local MCP server for COMSOL Multiphysics workflows. It exposes COMSOL automation, Desktop assistance, guided modeling workflows, validation tools, result extraction, and RAG-assisted documentation retrieval through one MCP interface.

Chinese documentation: README.zh-CN.md

This is an unofficial local automation project. It is not affiliated with, endorsed by, or supported by COMSOL AB.

Features

COMSOL automation: create, load, inspect, save, and solve COMSOL models through the Python mph backend.
Desktop assistance: inspect COMSOL Desktop windows, capture screenshots, use Java Shell fallback actions, and sync between GUI and mph sessions.
Modeling tools: parameters, components, geometry, selections, materials, physics, boundaries, mesh, studies, solving, plots, and exported results.
Guided workflows: built-in templates for common multiphysics tasks, next-step suggestions, step validation, and model completeness diagnostics.
RAG-assisted modeling: local ChromaDB retrieval over COMSOL documentation that you provide locally.
MCP integration: stdio MCP server for Claude Desktop and other MCP-compatible clients.

Repository Layout

.
├── src/comsol_agent_mcp/      # MCP server and core implementation
│   ├── server.py              # FastMCP tool entrypoint
│   ├── config.py              # Environment variables and local paths
│   ├── backends/              # mph and COMSOL Desktop backends
│   ├── tools/                 # Modeling, solving, plotting, GUI tools
│   ├── workflows/             # Workflow templates and step manager
│   ├── validators/            # Model setup and result validation
│   ├── knowledge/             # Embedded docs and RAG retrieval
│   └── assistants/            # Natural-language modeling assistant
├── scripts/                   # Knowledge-base utilities
├── tests/                     # Automated tests
├── knowledge_base/            # Placeholder docs for the local RAG index
├── env.local.example          # Local configuration template
├── start-comsol-mcp.cmd       # Windows launcher
└── pyproject.toml             # Python package metadata

Paths written as ./path/ are relative to the repository root.

Requirements

Python 3.10 or newer.
A licensed local COMSOL Multiphysics installation for mph automation.
Windows interactive desktop access if you want to use the GUI/Java Shell tools.
Optional: local COMSOL PDF documentation and an embedding service key if you want to build the RAG knowledge base.

The GitHub repository does not include COMSOL, private licenses, .mph model files, generated simulation results, the author's local Python environment, or a prebuilt vector database.

Installation

Clone or download the repository, then create your own Python environment from the repository root.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .[dev]
Copy-Item ./env.local.example ./env.local

Linux/macOS shell:

python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -e '.[dev]'
cp ./env.local.example ./env.local

Edit env.local for local paths, embedding settings, and optional GUI settings. Keep private API keys and machine-specific paths in env.local; do not commit that file.

Start the MCP server manually:

.\.venv\Scripts\python.exe -m comsol_agent_mcp.server

On Windows you can also run:

.\start-comsol-mcp.cmd

The launcher uses ./conda-envs/comsol-mcp/python.exe if you created that environment yourself; otherwise it falls back to python on PATH.

MCP Client Configuration

Configure your MCP client to run the same Python environment where you installed this package.

Generic stdio configuration:

{
  "mcpServers": {
    "comsol-multiphysics-mcp": {
      "command": "<absolute-path-to-python>",
      "args": ["-m", "comsol_agent_mcp.server"],
      "cwd": "<absolute-path-to-repository>"
    }
  }
}

Windows .venv example:

{
  "mcpServers": {
    "comsol-multiphysics-mcp": {
      "command": "D:\\path\\to\\COMSOL_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "comsol_agent_mcp.server"],
      "cwd": "D:\\path\\to\\COMSOL_MCP"
    }
  }
}

If the MCP client points to a different Python than the one used for pip install -e ., the server may fail to import dependencies or may not see the expected COMSOL/mph environment.

COMSOL and mph Troubleshooting

The mph_start tool starts a local COMSOL-backed mph session. The mph_connect tool connects to an existing COMSOL server, but the Python mph package still needs to load the local COMSOL Java API before it can connect.

If you see:

Did not recognize platform architecture.

the error is coming from mph while it maps your OS/CPU/Python runtime to a COMSOL platform folder such as win64. This is usually a deployment environment issue, not a COMSOL model issue.

Common causes:

32-bit Python on a 64-bit COMSOL installation.
Windows ARM64, MSYS/Cygwin Python, or WSL while COMSOL is installed only on Windows.
The MCP client is launching a different python than the environment where the project was installed.
COMSOL is not installed locally, or its registry/PATH entries are not discoverable by mph.
mph_connect is being run from a machine that does not have the local COMSOL Java API files.

Run these commands with the exact Python executable used by your MCP client:

python -c "import platform, sys; print(sys.executable); print(platform.system(), platform.machine(), platform.architecture())"
python -c "import mph.discovery as d; print(d.detect_architecture()); print(d.find_backends())"

On typical 64-bit Windows systems, the first command should report Windows, AMD64, and 64bit; the second should report win64 and list at least one COMSOL backend. If COMSOL is installed but no backend is found, repair the COMSOL installation, registry entries, or PATH so mph can discover bin/win64/comsolmphserver.exe.

Workflows

Workflows are lightweight modeling guides kept in the current MCP server process. They track the selected template, goal, current step, suggested tools, and validation hints. Restarting the server clears the active workflow, so call workflow_start again after a restart.

Built-in templates:

general
electrostatics
heat_transfer
fluid_flow
solid_mechanics

Shared step chain:

requirements -> parameters -> component -> geometry -> geometry_build -> materials -> physics -> boundaries -> mesh -> study -> solve -> results -> save_version

Typical sequence:

workflow_list_templates
workflow_start
workflow_next_step
run the recommended modeling tools
workflow_validate_current_step
repeat next_step/validate until complete
workflow_diagnose_model

RAG Knowledge Base

The RAG pipeline can build a local ChromaDB index from COMSOL documentation that you are licensed to use. Large PDF files and generated vector databases are intentionally not stored in Git.

Expected local folders:

pdf/                 # Your local COMSOL PDF documentation
knowledge_base/      # Generated ChromaDB index
cache/               # Local processing/model/package caches

If this repository provides release assets for documentation or a prebuilt knowledge base, download and extract them into the repository root:

Expand-Archive ./comsol-docs-pdf.zip ./pdf -Force
Expand-Archive ./comsol-rag-knowledge-base.zip ./knowledge_base -Force
python ./scripts/build_knowledge_base.py --status

To build from local PDFs under ./pdf/:

python ./scripts/build_knowledge_base.py --rebuild

To build from a cleaned package containing chunks.jsonl:

python ./scripts/build_knowledge_base.py --rebuild --from-package <rag_embedding_package>

Typical embedding settings:

DASHSCOPE_API_KEY=replace-with-your-dashscope-api-key
COMSOL_AGENT_EMBEDDING_MODEL=text-embedding-v4
COMSOL_AGENT_EMBEDDING_DIMENSION=1024
COMSOL_AGENT_EMBEDDING_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings

Main MCP Tools

Backend/session: backend_status, backend_set_default, mph_start, mph_connect, mph_status, mph_disconnect
Model/parameters: model_create, model_load, model_save, model_save_version, model_inspect, param_set, param_list
Geometry/materials/physics: geometry_create, geometry_add_block, geometry_add_cylinder, geometry_build, material_create_common, physics_add, physics_add_electrostatics, physics_add_heat_transfer
Boundaries/mesh/study: boundary_get_presets, boundary_add_condition, boundary_add_preset, mesh_create, mesh_build, study_create_stationary, study_solve
Results/plots: results_evaluate, results_global_evaluate, results_plots_list, plot_export_image, plot_export_geometry_view
Desktop: gui_status, gui_diagnose, gui_open_model, gui_ensure_java_shell, gui_execute_java_shell, gui_capture_window, gui_capture_graphics_panel
Workflows: workflow_list_templates, workflow_start, workflow_next_step, workflow_validate_current_step, workflow_diagnose_model
Validation/RAG/assistant: model_validate_all, physics_validate_setup, boundary_validate_conditions, mesh_validate, rag_status, rag_build, rag_search, modeling_assist

Tests

python -m pytest

Quick smoke test:

python -m pytest tests/test_workflows.py tests/test_rag_status.py

Acknowledgements

This project was developed with reference to ideas and implementation patterns from:

Notes

COMSOL and COMSOL Multiphysics are trademarks or registered trademarks of COMSOL AB.
This repository does not include COMSOL software, official COMSOL documentation, .mph model files, generated simulation results, private API keys, or private local caches.
COMSOL Desktop tools require Windows interactive desktop access and an installed COMSOL Desktop.
Java Shell execution is restricted by default to model. COMSOL Java API statements unless allow_non_model_code=true is explicitly set.

MCP Servers