Enables AI assistants to perform engineering physics simulations including thermal, structural, modal, DC, and laminar-flow studies on CAD models.
Also known as ottonic/simulation-mcp-server, simulation-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Oct 31, 2026
- License
- MIT
What is Ottosim MCP?
Ottosim enables AI assistants to perform engineering physics simulations including thermal, structural, modal, DC, and laminar-flow studies on CAD models.
Summary generated from the project's README
About Ottosim MCP server
Ottosim is a local stdio MCP server that allows AI assistants to perform first-order engineering physics simulations directly on CAD models. It processes STEP files through explicit meshing using Gmsh and executes typed studies within the Elmer solver. This setup operates entirely on the local machine without relying on cloud services, ensuring that all engineering inputs like materials, boundaries, and mesh settings are explicitly stated rather than inferred.
Developers can use the server to conduct steady and transient thermal, linear static structural, modal, DC conduction, and laminar flow studies. The server provides a structured workflow through tools such as inspect_model, prepare_study, and run_study. It supports various engineering units like mm, in, psi, and degC, converting them at the API boundary to maintain SI consistency. Every study and result is revision-bound, allowing users to trace specific numbers back to the exact parameters that produced them.
What you can do with it
- 1Perform steady thermal analysisRun a simulation to estimate the steady temperature and heat flux of a specific component.
- 2Conduct structural stress testingExecute a linear static structural study to determine displacement and stress summaries on a model.
- 3Analyze modal frequenciesIdentify the first few eigenfrequencies of a part to understand its vibrational characteristics.
- 4Simulate laminar fluid flowModel incompressible Newtonian fluids to observe pressure and velocity distributions.
Written from the project's README. Every use case is checked against a quote from it.
How to install Ottosim MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Ottosim MCP in Claude Code
$ claude mcp add simulation-mcp-server -- npx -y simulation-mcp-serverInstall Ottosim MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"simulation-mcp-server": {
"command": "npx",
"args": [
"-y",
"simulation-mcp-server"
]
}
}
}Install Ottosim MCP in VS Code
.vscode/mcp.json
{
"servers": {
"simulation-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"simulation-mcp-server"
]
}
}
}Install Ottosim MCP in VS Code CLI
$ code --add-mcp '{"name":"simulation-mcp-server","type":"stdio","command":"npx","args":["-y","simulation-mcp-server"]}'Install Ottosim MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"simulation-mcp-server": {
"command": "npx",
"args": [
"-y",
"simulation-mcp-server"
]
}
}
}Install Ottosim MCP in Codex
$ codex mcp add simulation-mcp-server -- npx -y simulation-mcp-serverInstall Ottosim MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.simulation-mcp-server] command = "npx" args = ["-y", "simulation-mcp-server"]
Install Ottosim MCP in Gemini CLI
$ gemini mcp add -s user simulation-mcp-server npx -- -y simulation-mcp-serverInstall Ottosim MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"simulation-mcp-server": {
"command": "npx",
"args": [
"-y",
"simulation-mcp-server"
]
}
}
}Configuration
SIMULATION_ELMERGRIDSIMULATION_ELMERSOLVERSIMULATION_INPUT_ROOTSSIMULATION_PYTHONSIMULATION_WORKSPACE
| Name | Description | |
|---|---|---|
| SIMULATION_ELMERGRID | — | |
| SIMULATION_ELMERSOLVER | — | |
| SIMULATION_INPUT_ROOTS | — | |
| SIMULATION_PYTHON | — | |
| SIMULATION_WORKSPACE | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableottonic/simulation-mcp-server is public and reachablegithub.com/ottonic/simulation-mcp-server ↗Pass
- Package names this repository as its sourcesimulation-mcp-server names ottonic/simulation-mcp-server as sourcenpmjs.com/package/simulation-mcp-server ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for simulation-mcp-servernpmjs.com/package/simulation-mcp-server/v/0.3.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/ottonic/simulation-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from simulation-mcp-serverPass
- No critical advisory in the package or its dependencies17 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOttosim — Simulation MCP Server
Give an AI assistant first-order engineering physics on a real CAD model. This local stdio MCP server carries a STEP file through explicit meshing in Gmsh to a typed study in Elmer — steady and transient thermal, linear static structural, modal, DC conduction, and laminar flow — and returns revisioned results, with no cloud service and no prepared solver input.
Every engineering input is explicit: the materials, boundaries, and mesh are stated, never inferred, and each study, mesh, and result is revision-bound so a number can always be traced back to what produced it.
Qualified against analytic references. Gmsh 4.15.2 and Elmer (devel, most
recently released as 26.2.1) complete production-SIF qualifications for every
advertised physics — steady and transient thermal, static structural, modal
frequency, DC potential, and steady and transient laminar flow — each against an
analytic reference with mesh (or timestep) refinement.
Runs on Node 26 / TypeScript 7 against MCP SDK 2.4.0, with a Python Gmsh worker over
a one-request/one-response JSON-file protocol (protocol: 1).
Install and launch
Distribution targets match Geometry MCP: Windows x64, macOS ARM64 (Apple Silicon), and Linux x64. Intel macOS, Linux ARM64, and Windows ARM64 are outside the target matrix. CI runs unit/artifact/process checks on these three targets, builds the pinned serial Elmer solver on each target, caches the native install, runs the analytic integration and qualification suites, then packs and smoke-tests the published tarball. This validates native execution; a standalone runtime package is not yet published.
The repository owns its artifact schema in contracts/. Builds bundle that
schema and the Python worker; Gmsh and Elmer runtimes are installed separately.
From this directory:
nix develop
just setup
just build
export SIMULATION_INPUT_ROOTS='["/absolute/path/to/models"]'
export SIMULATION_WORKSPACE=/absolute/path/to/run-workspace
just start
.envrc already contains use flake; direnv allow is an alternative to
nix develop. .env.example documents variables; .env is not auto-loaded.
just setup installs npm dependencies without lifecycle scripts. The flake
pins nixpkgs (and thus Gmsh) by commit, and pins upstream Elmer by commit.
Elmer's transitive inputs use its checked-in lock.
Nix provisions the solver toolchain only on x86_64-linux.
packages.<system>.toolchain provisions Node, Gmsh, the Python wrapper and
headless upstream Elmer built serially without MPI, OpenMP, ElmerIce or Lua. The analytic
thermal benchmark passes with that serial solver. The dev shell also provisions
Python, Ruff and Nix tooling;
TypeScript language server/formatter/linter/test deps are project-local npm
dependencies. Gmsh's Python module lives under its Nix package's lib, supplied
through PYTHONPATH. Elmer is an external package, not compiled by npm.
Non-Nix deployments must provide compatible Gmsh Python bindings and native
library plus ElmerGrid and ElmerSolver with HeatSolve, FluxSolver,
SaveData and ResultOutputSolve modules. Executables are operator configuration:
| Variable | Default / meaning |
|---|---|
SIMULATION_INPUT_ROOTS |
Required JSON array of existing absolute input roots |
SIMULATION_WORKSPACE |
.simulation-runs; local run/artifact storage |
SIMULATION_PYTHON |
python3 (Windows: python); Nix sets its wrapper |
SIMULATION_ELMERGRID |
ElmerGrid |
SIMULATION_ELMERSOLVER |
ElmerSolver |
SIMULATION_TIMEOUT_MS |
120000 per worker/conversion/solve; maximum 3600000 |
Generic host configuration example (environment may instead be inherited from the Nix shell):
{
"command": "node",
"args": ["/absolute/path/to/simulation/dist/src/index.js"],
"env": {
"SIMULATION_INPUT_ROOTS": "[\"/absolute/path/to/models\"]",
"SIMULATION_WORKSPACE": "/absolute/path/to/run-workspace",
"SIMULATION_PYTHON": "/absolute/path/to/provisioned/simulation-python",
"SIMULATION_ELMERGRID": "/absolute/path/to/ElmerGrid",
"SIMULATION_ELMERSOLVER": "/absolute/path/to/ElmerSolver"
}
}
Study tools
The public workflow is get_capabilities → inspect_model → query_model →
validate_study → prepare_study → run_study → inspect_job →
query_results. list_jobs recovers recent jobs after context loss and
cancel_job stops an active preparation or solver process.
inspect_job accepts waitMs (up to 60 s) and then waits in-process for a
terminal state instead of returning immediately, so
prepare_study → inspect_job(waitMs) → run_study → inspect_job(waitMs) → query_results is normally five calls rather than dozens of polls. The state
is returned whether or not the window expires. A cancelled or timed-out
client request stops the mesh or the solve: ctx.signal is forwarded to the
job's abort path and the record ends cancelled. Preparation and
solver execution return job IDs immediately. Jobs survive client disconnects,
not server shutdown. Interrupted jobs are recorded and are not resumed.
get_capabilities reports the available physics and the study shape
(required and optional fields, notes, and a worked example); the machine-readable
simulation://help resource carries the full study schema — per-physics
material and boundary fields with units, regimes, observation quantities with
time/mode selectors, enums, and a parseable example. Both are generated from one
catalog so discovery cannot drift from the accepted study schema.
steady-thermal, transient-thermal, static-structural, modal,
dc-conduction, and laminar-flow are implemented and benchmarked. Other physics reported by
get_capabilities remain unavailable, not implied by the fact that Elmer has
upstream solvers for them.
Transient studies require explicit density and heat capacity per solid,
one uniform initial temperature, a positive timestep, and a step count capped
at 10,000. Fixed-temperature, insulated and inward-heat-flux boundaries are
supported; time-varying conditions and per-region initial
temperatures are not. Transient scalar and VTU results are validated at every
step. An observation may select a positive timestep-aligned time in seconds;
without time, it observes the final step. Acceptance thresholds remain in the
quantity's units (for example, K), not seconds.
Static structural studies require an explicit isotropic Young's modulus and Poisson ratio for every solid, and an explicit fixed-displacement, prescribed-displacement, uniform-traction, or free condition for every surface. The supported model is static, linear-elastic, and small-strain; displacement and stress summaries are unweighted nodal samples, not volume averages.
Modal studies require explicit density in addition to elastic properties, fixed-displacement/free surface assignments, and request 1–20 modes. The first modal implementation reports eigenfrequencies only; it does not expose mode shapes, damping, prestress, or harmonic response. Modal observations select a mode number and use Hz.
DC conduction studies require explicit positive isotropic electrical conductivity per solid, explicit prescribed-potential or insulated conditions on every surface, and at least two distinct prescribed potentials per disconnected conductive component. Results report the nodal potential field; current, Joule heating, magnetic effects, and transient/capacitive behavior are not modeled.
Laminar-flow studies model incompressible Newtonian fluids with explicitly
assigned constant density and dynamic viscosity. Every fluid surface must be
explicitly assigned either a prescribed pressure or a no-slip wall; each
disconnected fluid region needs at least two distinct prescribed pressures.
Steady and transient runs are supported; transient runs use first-order BDF,
constant timestep, and an explicit quiescent initial velocity. The solver is
Elmer's monolithic FlowSolve module; qualification covers pressure-driven
square-duct flow and transient startup against the analytic rectangular-duct
solution, inlet/outlet flux conservation, and mesh/timestep refinement. Flux and
section averages are not exposed; reported velocity and pressure values are nodal
extrema. Elmer's segregated IncompressibleNS module is installed but not
qualified. Turbulence, compressibility, moving walls, nonzero initial velocity,
and thermal/electric coupling are not modeled.
Selections use dimension-qualified inspection entity IDs (for example 3:1
for a volume or 2:7 for a surface), have unique names and cannot mix solids
and surfaces. Every inspected entity must be assigned exactly once. Each solid
selection needs one material; every surface selection defaults to insulated
in thermal studies unless explicitly overridden. Structural, modal, and DC
studies require explicit conditions on every surface. A thermal default is a
declared engineering assumption, not an inferred boundary condition. The
solver uses SI units, but study quantities may be supplied in compatible
engineering units (for example mm, in, psi, ksi, lbf, degC) and are
converted at the API boundary. Mesh sizes default to metres and accept mm,
cm, in or ft through mesh.units. Results are SI by default; an optional
displayUnits block (for example { "length": "in", "pressure": "ksi" })
returns observations in the engineer's units. Linear tetrahedra are still the
only supported element type.
Material entries may carry an optional reference with the designation, source
name/revision, and basis returned by a reference tool such as Standards. The
study preserves this caller-supplied context alongside the explicit numeric
properties; Simulation does not fetch or verify the source. A typical value
remains distinct from a qualified design allowable.
Example steady thermal study after inspecting the STEP file:
{
"schemaVersion": "1",
"name": "Bar conduction",
"objective": "Estimate the steady temperature and heat flux",
"model": {
"source": {
"revision": "sha256:<64 lowercase hex digits>",
"uri": "file:///.../source.step",
"format": "step",
"units": "mm"
},
"inspection": {
"revision": "sha256:<64 lowercase hex digits>",
"uri": "file:///.../inspection.json",
"format": "json"
}
},
"selections": [
{ "name": "bar", "entities": ["3:1"] },
{ "name": "hot_end", "entities": ["2:2"] },
{ "name": "cold_end", "entities": ["2:3"] },
{ "name": "other_faces", "entities": ["2:4", "2:5", "2:6", "2:7"] }
],
"mesh": { "minSize": 0.003, "maxSize": 0.006, "elementOrder": 1 },
"physics": {
"kind": "steady-thermal",
"defaultBoundary": "insulated",
"materials": [
{
"selection": "bar",
"conductivity": { "value": 10, "units": "W/(m.K)" }
}
],
"sources": [],
"boundaries": [
{
"selection": "hot_end",
"kind": "temperature",
"temperature": { "value": 400, "units": "K" }
},
{
"selection": "cold_end",
"kind": "temperature",
"temperature": { "value": 300, "units": "K" }
}
]
},
"observations": [{ "id": "max_temperature", "quantity": "temperature_max" }],
"acceptanceCriteria": [
{
"observationId": "max_temperature",
"operator": "<",
"threshold": { "value": 410, "units": "K" }
}
],
"assumptions": []
}
The example entity tags are illustrative; use tags from query_model and
confirm each selection against the actual part. prepare_study returns a
jobId; poll inspect_job until it succeeds, then pass its prepared artifact
to run_study, which returns another jobId. query_results reports solver
evidence separately from observation
values and criterion outcomes; a failed criterion is an engineering result, not
a solver error. Its response is bounded by default — observation values without
duplicate backing summaries, de-duplicated field descriptors, and one page of
artifact refs (limit/cursor, artifactCount). Summaries are returned when
requested with include:["summaries"], or as a fallback when no observations
were declared. Pass time to select one frame or observations to filter. Scalar
means are nodal, not volume averages or integrated heat
rates. Arbitrary SIF, procedures, expressions, scripts and solver commands are
never study inputs.
Tool failures use MCP isError. Domain failures from the service return a JSON
{ code, message } object (with revisioned diagnostic log refs where available);
invalid tool arguments are rejected by the MCP layer before the handler runs and
are returned as plain text. The domain error codes are a closed, documented set
(listed under enums.error_codes in simulation://help): invalid_input,
invalid_study, invalid_physics, invalid_selection, invalid_job_kind,
unsupported_condition, unsupported_physics, unsupported_format,
stale_artifact, path_policy, file_not_found, too_large, bad_mesh,
bad_groups, malformed_results, solver_failed, worker_failed,
conversion_failed, process_failed, spawn_error, output_limit,
persistence_failed, cancelled, timeout, interrupted, worker_protocol,
and internal_error. Failed solves return inspectable run metadata rather than
disguising partial outputs as successful results.
Server diagnostics are written as newline-delimited JSON to stderr (stdout is the
MCP channel). Set MCP_LOG_LEVEL (debug|info|warn|error, default
info), MCP_LOG_FORMAT=human for a compact form, and
MCP_TRACE_ID to correlate events; secret-like fields are redacted.
Boundaries, security and retention
- This is a trusted-local tool, not a filesystem sandbox. Input roots are canonicalized and used to catch accidental path mistakes; the server assumes the local user and files are trusted. Do not expose it to untrusted clients.
- Artifact revisions are SHA-256 digests of the exact bytes read or produced. Reusing a ref after its file changes fails explicitly, but concurrent edits during an operation are not defended against.
- Processes use configured executables and argument arrays, no shell. The local process environment is inherited for runtime compatibility, with deterministic locale/thread settings applied; child tools therefore also inherit local env vars.
- Per-process wall timeout, serial execution and 8 MiB combined captured-output bound are enforced. There is no portable memory, mesh-size, input-size or workspace-disk quota; provision OS quotas/cgroups if deployment needs them.
- V1 supports separate solid regions and exterior BC groups. Internal/orphan native boundaries fail; no contact resistance, automatic fragmentation, repairs, nonconformal coupling, radiation, plasticity, or geometric nonlinearity. Transient thermal supports only the explicit constant-property/ time-step model above; structural support is isotropic, linear small-strain; modal support is undamped and unloaded.
- Selectors are tied to exact source revision, Gmsh version and
gmsh-occ-import-v1. No Geometry SubjectRef-to-Gmsh topology equivalence is claimed. Imported names are hints, never engineering intent. - No automatic deletion. Shut down the server, then explicitly archive/remove
UUID operation directories when refs are no longer needed.
just cleanremoves only compiled code. Interrupted records are not resumed. After an ungraceful termination inspect/reap any orphaned solver processes before restarting against that workspace. Graceful shutdown cancels owned runs. - Hosted deployments need an external isolation boundary (e.g. a container or VM with explicit input mounts and resource limits); application path checks are not a substitute. These outputs are numerical evidence, not engineering certification.
Implementation choices
- The Gmsh Python API owns STEP import, topology inventory, and mesh generation.
It communicates with TypeScript through a bounded JSON-file worker protocol;
no generated
.geoscript is required. - Typed inputs generate deterministic SIF. PyElmer and model-authored SIF are unnecessary for supported workflows.
- ASCII MSH 2.2 transfers explicit physical groups to ElmerGrid; converted group membership and connectivity are verified instead of trusting labels alone.
- Upstream Elmer and Gmsh are external tools provisioned by Nix, not downloaded by npm at server startup. Non-Nix deployments can configure executable paths.
- Scalar summaries and VTU inventory are intentionally limited to the supported solver output. Geometry IDs are not cross-kernel mesh selectors.
Artifact references
Every reference identifies one exact byte stream with revision: "sha256:<64 lowercase hex digits>" and a format. A URI is an optional locator; operations
requiring bytes need an accessible local file: URI. Supported format identifiers
are step, gmsh-msh, elmer-mesh, vtu, elmer-sif, text, and json.
Derived artifacts receive their own digests. An Elmer mesh directory is not a
single artifact: its metadata references individual native files.
Limits
- Linear tetrahedra only; studies are small-strain and use the physics kinds listed above. Every engineering input is explicit — materials, boundaries, and idealisations are never inferred.
- Results are numerical evidence, not engineering certification; a failed acceptance criterion is an engineering result, not a solver error.
- A job survives a client disconnect but not a server shutdown, and interrupted jobs are recorded rather than resumed.
Development
Requires Node.js 26+ and just. A Nix flake and
.envrc provide the toolchain; run direnv allow after changing either.
| Recipe | Purpose |
|---|---|
just setup |
Install dependencies (npm scripts disabled). |
just dev |
Run the server over stdio. |
just start |
Run the compiled server. |
just build |
Compile into dist/. |
just test |
Run solver-independent unit tests. |
just test-integration |
Run the opt-in Gmsh/Elmer integration benchmark. |
just lint |
Run oxlint. |
just fmt |
Rewrite formatting with Prettier. |
just fmt-check |
Verify formatting. |
just typecheck |
Run tsc --noEmit. |
just check |
fmt-check + lint + typecheck + test. |
just fixture |
Regenerate the analytic bar fixture. |
just clean |
Remove build output. |
Server logs go to stderr as newline-delimited pino JSON. MCP_LOG_LEVEL
(debug|info|warn|error), MCP_LOG_FORMAT=human, and MCP_TRACE_ID tune
them; secret-like fields are redacted.
The lightweight checks shell includes Node and Ruff without building the
Gmsh/Elmer solver toolchain:
# Run from this repository.
nix develop .#checks --accept-flake-config --command just setup
nix develop .#checks --accept-flake-config --command just check
nix develop --accept-flake-config --command just test-integration
nix develop --accept-flake-config --command just check
nix develop --accept-flake-config --command just build
just test-integration runs the opt-in direct-service Gmsh/Elmer benchmark. It is
server-owned integration coverage; public stdio acceptance runs separately
against the built server artifact.
In a source checkout, tests/fixtures/README.md documents analytic bar dimensions,
generation, and temperature/heat-flux tolerances. Unit checks do not require a
solver runtime. Native integration checks additionally cover malformed inputs,
solver failures, timeout/cancellation, restart persistence, and stale outputs.
Tests use the operating system's temporary directory;
SIMULATION_TEST_TMP can select another temporary root.
Licensing and upstream source references are recorded in third-party notices.
Packaging
npm pack builds first and includes compiled runtime code, the local artifact
schema, Python worker, README, and third-party notices. Tests, source maps, and
Python caches are excluded. Install the tarball to check simulation-mcp-server
with a compatible MCP client. The server serves both protocol eras: the
2025-11-25 handshake that stock MCP hosts negotiate, and 2026-07-28
through server/discover. Native tools still require separate installation.
just check includes solver-independent stdio protocol tests for modern
discovery, workflow resources, tool errors, and both protocol eras.
License
MIT. Third-party toolchain terms are in THIRD_PARTY_NOTICES.md.
Ottosim MCP questions
How do I add Ottosim MCP to Claude Code?
Run claude mcp add simulation-mcp-server -- npx -y simulation-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Ottosim MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What types of physics studies can Ottosim perform?
The server supports steady and transient thermal, linear static structural, modal frequency, DC conduction, and steady and transient laminar flow studies.
Does this server require a cloud service?
No, it is a local stdio MCP server that runs without a cloud service.
What file format is required for the CAD models?
The server processes STEP files.
Can I use non-standard engineering units?
Yes, while the solver uses SI units, the API allows you to supply quantities in compatible units like mm, in, psi, ksi, lbf, or degC.