starccm-mcp

An unofficial MCP server for Simcenter STAR-CCM+. It lets an AI assistant such as Claude Code, Claude Desktop or any other MCP client:

• read a .sim file without STAR-CCM+ and without a licence: version, mesh size, regions, boundary conditions with their values, global parameters, physics models, reports, stopping criteria and the full history of every monitor;

• read solver logs: the iteration table, AMG divergences, reversed flow, limited cells and stopping criteria, with licence keys masked;

• search the documentation of your own installation, including the user guide and the Java API reference, so macros are written against methods that exist;

• run Java macros on a simulation you already have open, through a batch client, with guard rails.

It was written by a student who needed to understand someone else's .sim at midnight without a licence seat free. If you have ever had to guess why a case diverged or what a teammate set on a boundary, this is for you.

Not affiliated with, endorsed by or supported by Siemens. Simcenter and STAR-CCM+ are trademarks of Siemens Digital Industries Software. This repository contains no Siemens code or documentation: the documentation tools read the files of your local installation.

Tools

¹ Option names, such as Components instead of index 1, are looked up in the local Java API reference when it is installed.

Related MCP server: COMSOL MCP

Install

You need Python 3.10 or newer. The .sim and log tools are plain Python and run anywhere. The session tools are Windows-only for now.

git clone https://github.com/RHerAle/starccm-mcp
cd starccm-mcp
python -m venv .venv
.venv\Scripts\pip install -e .

Add it to Claude Code:

claude mcp add starccm -- C:\path\to\starccm-mcp\.venv\Scripts\starccm-mcp.exe

Or to Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "starccm": { "command": "C:\\path\\to\\starccm-mcp\\.venv\\Scripts\\starccm-mcp.exe" }
  }
}

The installation is found under C:\Program Files\Siemens\*\STAR-CCM+*. If yours is somewhere else, set STARCCM_HOME to the folder that contains star\ and doc\.

Safety

• .sim files are only opened for reading.

• Licence data is masked. STAR-CCM+ puts the Power-on-Demand key and the licence server on the command line of every server process, and logs can repeat them. Log text and macro output are masked by masking.py as a whole, before any filtering or truncation; process command lines are never returned. The masking works by patterns, so treat it as a strong safeguard, not a guarantee.

• The log tools read any text file you point them at. They are meant for STAR-CCM+ logs; the path is not restricted.

• Macros are checked before they run, but the check is not a sandbox. It reads the source with patterns to catch an assistant's mistakes before they reach your live session. A macro that runs has your full rights and the server's: it can write files, open connections or check out licences. Never run a macro you do not trust. The rules come from a real accident: a "read-only" macro that called getters by reflection reached unloaded 3D-CAD sketches on a parallel server. The server died with Non-recoverable ... isSerialCritical and took the open simulation with it.

  • Refused: Java reflection, class loading, System.exit and System.getenv, Runtime and processes, network classes and script engines.

  • Refused unless allow_risky=True: 3D-CAD access, saveState, deleting or clearing objects and data, closing the simulation, running the solver, meshing and writing files. The assistant should only set it after you agree to that specific action.

  • Known limits: the patterns look at names, not types, so they can be evaded (for example by storing the simulation or a Class object in another variable first), file writes through STAR-CCM+'s own APIs are only partly recognised, and Java has more ways to reach the outside than any list can name.

  • expected_sim refuses to run if the window on that port shows a different simulation.

  • On a timeout, only the batch client is killed. The server and your GUI keep running.

• The MCP server itself never starts a STAR-CCM+ server, never checks out a licence and makes no network connections. What a macro does once it runs is up to the macro.

How the .sim reader works

Siemens does not document the format. This is what was observed on files saved by STAR-CCM+ 2502 (20.02):

• The first line is a dict with 'StatePosition': N.

• From byte N to the end of the file, each line is one object written as a Python-like dict, and object r sits on line r + 2.

• Integers with an L suffix are usually references to other objects.

• Monitor histories are MasterArray<Float8> records. Their dataKey is the absolute byte offset of a one-line header followed by little-endian doubles.

Only the object state is parsed, never the mesh or the solution arrays, so a 250 MB .sim opens in about 0.3 s.

Status and limitations

• Tested with STAR-CCM+ 2502 (20.02.008) on Windows 11. Other versions are untested; reports are welcome.

• Solution fields stored in the .sim, such as density on a boundary, are not exposed yet.

• An expression's stored value is the last one STAR-CCM+ evaluated; the definition is always current.

• The session list reads the open simulation from the GUI window title. Without a GUI, use starccm_session_info.

Development

.venv\Scripts\pip install -e ".[test]"
.venv\Scripts\python -m pytest

The tests build a tiny synthetic .sim and a synthetic log, so they need neither STAR-CCM+ nor real files.

En español

Servidor MCP no oficial para STAR-CCM+. Lee un .sim sin abrir STAR-CCM+ ni gastar licencia: contornos con sus valores, parámetros, modelos, criterios de parada e historial de los monitores. También lee el log, busca en el manual y el javadoc de tu propia instalación y lanza macros contra una sesión abierta, con comprobaciones para evitar errores que la tumben (no son un sandbox). Instalación y uso, arriba. Licencia GPL-3.0-only: si lo redistribuyes, modificado o no, tu versión debe seguir siendo GPL, conservar la atribución a este proyecto en sus avisos legales y, si está modificada, indicarlo (detalles en NOTICE).

Licence

© 2026 RHerAle. Code under GPL-3.0-only (LICENSE), with additional terms under section 7 of the GPL (NOTICE): every copy and every modified version must keep the author attribution in its legal notices, and a modified version must be marked as different from the original and must not be presented as the original.

Forks and variants

If you publish a variant, please make it a GitHub fork and add it to VARIANTS.md with a pull request, so other users can find it. This is a request, not a licence condition.

Contributing

Pull requests are welcome, with no agreement to sign: contributions are licensed under the same terms as the project, and each commit carries a Signed-off-by line (git commit -s). See CONTRIBUTING.md.