COMSOL Codex MCP

An MCP server and agent toolkit for reproducible COMSOL Multiphysics batch workflows.

This project is intentionally generic. It does not encode one specific COMSOL model. Instead, it gives AI agents a safe, auditable way to:

• discover a local COMSOL installation;
• compile Java API model scripts with comsolcompile;
• run compiled classes with comsolbatch;
• monitor and diagnose logs;
• search COMSOL completion XML for Java API feature/property names;
• collect lightweight result packages while excluding .mph, raw dumps, logs, and generated classes;
• expose reusable COMSOL automation recipes to Codex/Claude-style agents through MCP tools.

Why This Exists

Several COMSOL MCP projects focus on GUI automation or Python MPh/mphserver workflows. This project focuses on the engineering loop that coding agents often need:

write Java API model -> compile -> batch run -> inspect log -> parse output -> package results

That loop is useful for long-running, reproducible simulation jobs where opening COMSOL Desktop is undesirable or impossible.

Install

python -m pip install -e .

To run as an MCP server:

python -m pip install -e ".[mcp]"
comsol-mcp-server

To use the standalone CLI:

comsol-tool find-install
comsol-tool search-feature ThermalContact
comsol-tool inspect-log path/to/batch.log

Documentation

• Quickstart
• Tool reference
• Architecture
• Recipes
• Safety
• Compatibility
• Comparison with related projects
• Examples
• Roadmap
• Contributing
• Security policy

MCP Tools

The server exposes:

Example Agent Workflow

1. Call comsol_find_install.
2. Ask the model to generate or modify a Java API script.
3. Call comsol_compile.
4. If compilation fails, use the compiler output and comsol_search_feature.
5. Call comsol_batch with a bounded timeout.
6. If the run is slow or fails, call comsol_inspect_log.
7. Parse model stdout with a project-specific parser.
8. Call comsol_collect_outputs to create an uploadable result bundle.

COMSOL Setup

The install finder checks:

• COMSOL_HOME
• COMSOL_ROOT
• PATH
• common Windows locations such as C:\Program Files\COMSOL and E:\Program Files\COMSOL
• common Linux locations such as /usr/local/comsol and /opt/comsol

If discovery fails, set:

COMSOL_HOME=/path/to/COMSOL63

On Windows PowerShell:

$env:COMSOL_HOME = "E:\Program Files\COMSOL\COMSOL63"

Safety Model

This toolkit is deliberately conservative:

• it uses subprocess.run([...], shell=False);
• it keeps compile/run operations explicit;
• it separates stdout, stderr, and batch logs;
• it excludes heavy/generated files from packages by default;
• it provides diagnostics rather than hiding COMSOL failures.

You should still run it only on trusted COMSOL Java scripts. A COMSOL Java class can create, solve, and save models on your machine.

What This Is Not

• It is not a replacement for COMSOL Desktop.
• It is not a universal physics model generator.
• It does not ship COMSOL, licenses, or proprietary documentation.
• It does not guarantee that a generated Java API script is physically valid.

Related Work

Existing public projects include GUI-driven COMSOL MCP servers, MPh/mphserver-based MCP servers, and Pythonic COMSOL scripting interfaces. This project aims to complement them with a batch-first, Codex-friendly, reproducible Java API workflow.

Trademark Notice

COMSOL and COMSOL Multiphysics are trademarks or registered trademarks of COMSOL AB. This project is independent and unofficial. See NOTICE.md.