COMSOL MCP

AI-driven MCP server for COMSOL with a visible Desktop client workflow.

comsol-mcp is built for the workflow where:

• you manually start COMSOL Multiphysics Server
• COMSOL Desktop connects to that server as a visual client
• an MCP client attaches to the same server-side model
• modeling changes remain visible instead of running as a black-box batch job

This repository is the new mainline for visible COMSOL automation in this codebase. The old batch-oriented route is now a legacy reference only.

Why This Project Exists

Many COMSOL automation flows are powerful but opaque. They can compile Java, run batch jobs, or drive generic server-side simulations, but they do not always let you watch the model evolve in the Desktop GUI.

comsol-mcp focuses on a different goal:

• visible GUI changes
• shared server-side model state
• no Desktop-side polling bridge
• no GUI automation layer
• no black-box batch-only workflow

Core Workflow

This project uses an attach-first workflow:

1. Start COMSOL Multiphysics Server manually.
2. Note the real listening port from the server console.
3. Connect COMSOL Desktop to that same port.
4. Import the server-side model into Desktop if needed.
5. Attach MCP to the same server with server_connect(host, port).
6. Create or load the working model.
7. Use MCP tools to modify the shared server-side model.
8. Watch the same model update in COMSOL Desktop.

See the workflow guide for the full version.

Quick Start

Prerequisites

• Windows with COMSOL installed locally
• A valid COMSOL license
• Python 3.10 or newer
• A manually started COMSOL Multiphysics Server

Install

From source:

git clone <your-repo-url> comsol-mcp
cd comsol-mcp
python -m pip install -e .

Set environment variables:

$env:COMSOL_ROOT = "C:\Program Files\COMSOL\COMSOL63\Multiphysics"
$env:COMSOL_SERVER_MCP_HOME = "$PWD\comsol-server-home"

Start the MCP server:

python -m comsol_mcp.mcp_server

Or use the helper script:

.\scripts\start_comsol_mcp.ps1 -Python python -ComsolRoot "C:\Program Files\COMSOL\COMSOL63\Multiphysics" -McpHome "$PWD\comsol-server-home"

MCP Config Example

See:

• examples/claude_desktop_config.json
• .mcp.json

Minimal Visible Demo

server_connect("localhost", <actual_port>)
model_create("VisibleServerModel")
ensure_component("comp1", 2)
ensure_geometry("comp1", "geom1", 2)
ensure_mesh("comp1", "mesh1")
create_feature("comp1", "geom1", "r1", "Rectangle", "[{\"name\":\"size\",\"values\":[\"60[mm]\",\"30[mm]\"]},{\"name\":\"pos\",\"values\":[\"-30[mm]\",\"-15[mm]\"]}]", true)
run_feature("mesh", "mesh1", "comp1")

Desktop should show the same geometry because Desktop and MCP share the same server-side model.

See examples/attach_first_demo.md for the same flow in document form.

Tool Surface

Current tools:

• server_info()
• server_start(...)
• server_connect(host, port, model_name="")
• server_disconnect(shutdown_server=false)
• model_create(name="Server Model")
• model_load(path)
• model_tree()
• get_parameters()
• set_parameters(parameters_json)
• ensure_component(component="comp1", dimension=2)
• ensure_geometry(component="comp1", geometry="geom1", dimension=2)
• ensure_mesh(component="comp1", mesh="mesh1")
• create_feature(component, geometry, tag, feature_type, properties_json="[]", run_geometry=false)
• update_feature(component, geometry, tag, properties_json, run_geometry=false)
• delete_feature(component, geometry, tag, run_geometry=false)
• run_feature(collection, tag, component="comp1")
• run_study(study_tag="")
• save_model(path="")

The modeling tool surface is intentionally stable. This repository cleanup does not rename or remove these tools.

Recommended Entry Point

The recommended entrypoint is:

server_connect("localhost", <actual_port>)

server_start() is still available, but it is now an advanced fallback. Use it only when you want MCP to own the COMSOL server lifecycle and accept that COMSOL may choose a different listening port automatically.

Known Limitations

• COMSOL Desktop may not automatically display the server-side model after a successful connection; you may need to import or switch to the existing server model.
• server_connect() can succeed while no current working model is selected; in that case use model_create() or model_load().
• The server console output and the actual listening port should always be verified against the real active listener.
• Desktop graphics may require a light refresh after server-side model changes.

See the troubleshooting guide.

How This Differs From Other MCPs

Versus abaqus-mcp-server

abaqus-mcp-server is a GUI scripting / GUI automation style project. It works with an already running GUI and uses GUI automation techniques to trigger actions.

comsol-mcp does not use pywinauto-style GUI automation for COMSOL. Instead, it attaches directly to COMSOL Multiphysics Server and drives the same server-side model that Desktop visualizes.

Versus generic COMSOL automation MCPs

Public COMSOL MCP listings often emphasize solver breadth, mesh generation, physics setup, and parametric sweep coverage.

This project emphasizes a different value proposition:

• attach-first
• visible Desktop workflow
• non-black-box modeling
• shared model state between Desktop and MCP

It is not just "another COMSOL automation MCP"; it is specifically about making the workflow visible and collaborative with the Desktop client.

Versus the old batch route

The old batch route used:

• comsolcompile
• comsolbatch

That route is still useful for offline jobs, but it is no longer the public identity of this project. In this repository, it is treated as a legacy reference rather than the mainline.

See docs/differences.md for a fuller comparison.

Legacy / Previous Batch Route

An earlier internal comsol-mcp route in this codebase was batch-oriented and wrapped comsolcompile plus comsolbatch. That legacy route is intentionally not the public face of this repository.

This repository focuses on:

• COMSOL Multiphysics Server
• Desktop as a visual client
• MCP attach to the same model

Attribution

• Built on top of MPh
• Inspired by COMSOL client-server workflows and related MCP explorations
• Not affiliated with COMSOL
• Does not include COMSOL binaries or proprietary assets

License

MIT. See LICENSE.