Kratos MCP Server

Appearance

Troubleshooting ​

Kratos not found ​

Symptom: kratos_check_installation returns importable: false, tools report "Kratos is not available".

  • Set KRATOS_ROOT to a checkout that contains bin/Release/KratosMultiphysics/.
  • If your build lives elsewhere, set KRATOS_PYTHONPATH (dir containing KratosMultiphysics/) and KRATOS_LIBS (its libs/).
  • Remember the variable must reach the server process: pass it via the MCP client's env block, not just your shell.

libmkl_rt.so.2: cannot open shared object file ​

The LinearSolversApplication was built against Intel MKL. The server auto-detects MKL at /opt/intel/oneapi/mkl/latest/lib; if yours is elsewhere:

bash
export KRATOS_EXTRA_LIBS=/path/to/mkl/lib

Simulation runs but displacements are exactly zero ​

Almost always: the mesh uses geometric conditions (LineCondition2D2N, SurfaceCondition3D4N) where load conditions are needed (LineLoadCondition2D2N, SurfaceLoadCondition3D4N). Geometric conditions silently ignore LINE_LOAD/SURFACE_LOAD. The solver even prints a hint:

ResidualBasedBlockBuilderAndSolver: ATTENTION! setting the RHS to zero!

Regenerate the mesh with the right condition_name (the tool defaults are correct for structural cases), or apply a nodal/volume load instead.

Error: Element ... is not registered in Kratos ​

  • The application registering that element is not compiled into your build — check with kratos_list_applications, and kratos_list_elements shows a compiled flag per element.
  • Watch the exact spelling and node count (SmallDisplacementElement2D4N exists; LaplacianElement2D4N does not — the Laplacian family only has simplex variants).

Found a condition without any corresponding element (thermal/fluid) ​

The convection-diffusion solver's mesh checks require simplex meshes. Generate thermal meshes with triangles: true and element_name: 'Element2D3N'. Every condition must also be a face of some element — generated meshes guarantee this.

Stationary thermal analysis behaves like one transient step ​

solver_type: stationary still uses the transient element by default. A true steady state needs:

json
"element_replace_settings": { "element_name": "LaplacianElement", "condition_name": "ThermalFace" }

The thermal_stationary template includes this.

Job stuck in running / server restarted mid-run ​

Jobs are detached processes; a server restart does not kill them. job_status re-evaluates state from pid liveness and the log tail. If a pid was reused and the state looks wrong, job_cancel forces the record to cancelled.

Interactive session is busy, dead or lost ​

  • busy: true (from session_advance): the call outlived its timeout but the worker is still solving. It is not lost — poll session_status until busy is false, then continue. Raise timeout for long steps.
  • dead: the Kratos process exited (usually a C++ abort on bad input or a diverged solve). session_status(session_id, log_tail=60) shows the exit code and the end of session.log; fix the case and session_start again. The MCP server itself is unaffected.
  • lost: the session belonged to a previous server process. Sessions live in memory and do not survive a restart; start a new one (use a batch job with checkpoints for work that must survive).
  • session_exec_python is disabled: start the server with KRATOS_MCP_ALLOW_EXEC=1 (for example claude mcp add kratos -e KRATOS_MCP_ALLOW_EXEC=1 -- uvx kratos-mcp-server). It runs arbitrary code as your user, which is why it is opt-in.
  • Too many open sessions: close one with session_close, or raise KRATOS_MCP_MAX_SESSIONS (default 4).
  • Multi-stage cases cannot be stepped / CoSimulation ... cannot be stepped / Partitioned FSI cases cannot be stepped / Cases with an mmg_process ... cannot be stepped / serial/OpenMP only: sessions drive one AnalysisStage; use run_simulation for orchestrated, coupled-solver or MPI cases.

MMG remeshing is not available / remeshed run dies with SIGSEGV ​

  • mesh_remesh and validate_case need a KratosMeshingApplication built with MMG. The pip wheel has it: kratos_install(applications=["MeshingApplication"]); a local build needs -DUSE_MMG=ON.
  • A job that crashes (returncode -11) right after MMG Remeshing Process: Remesh finished has an mmg_process that remeshes inside the solution loop. Standard solvers cannot survive that; use initial_remeshing: true or mesh_remesh on the .mdpa.
  • There is no sub model part with name "X" in model part "Y": freeze_sub_model_parts and fix_contour_model_parts take names relative to the root model part (left, not Main.left).

No MPI launcher available / no MPI support ​

run_simulation(mpi_ranks=N) checks before creating a job that an MPI launcher exists (mpiexec, mpirun, or KRATOS_MPI_LAUNCHER) and that the Kratos build can import KratosMultiphysics.mpi. kratos_check_installation reports both under mpi. The pip wheels are serial; use a build with -DUSE_MPI=ON (and TrilinosApplication for the Trilinos solver presets). If the launcher refuses more ranks than cores, add KRATOS_MPI_ARGS=--oversubscribe (OpenMPI). MPI jobs also require problem_data.parallel_type: "MPI".

Tool calls are slow the first time ​

The first bridge call after a (re)build spawns a Kratos interpreter (~1–3 s) and repopulates the disk cache under ~/.kratos-mcp/cache/. Later calls are instant. Deleting that directory is always safe.

model_part_name '...' does not match any SubModelPart ​

validate_case compares every model_part_name in your processes and materials against the mesh. Names are dotted paths rooted at the solver's model_part_name — for a solver rooted at Structure and a mesh part left, write Structure.left. Use mdpa_inspect to list the parts a mesh actually contains.

Debugging a failed run ​

  1. job_status(job_id) — how far did it get (progress.current_step)?
  2. job_logs(job_id, tail=200) — the Python traceback or Kratos error is at the end.
  3. results_convergence(job_id) — nonlinear steps that hit max_iteration.
  4. validate_case(case_dir) — re-check the configuration.

The debug_failed_simulation prompt packages this workflow.