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:

Tool	Purpose
comsol_find_install	Locate comsolcompile, comsolbatch, and comsol
comsol_compile	Compile a COMSOL Java API model
comsol_batch	Run a compiled class with comsolbatch
comsol_tail_file	Read the tail of a log/output file
comsol_inspect_log	Detect common COMSOL errors and progress markers
comsol_search_feature	Search physics.xml/common.xml for Java API hints
comsol_collect_outputs	Zip lightweight scripts/summaries/CSV outputs
comsol_clean_generated	List or remove generated class/status/recovery files
comsol_list_recipes	List built-in workflow recipes
comsol_get_recipe	Read a built-in workflow recipe

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.