Skip to main content
Glama
Lecoeurdelest

mujoco-mcp

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
MUJOCO_MCP_MODEL_ROOTSNoColon-separated allowlist of directories `file_path` may load from
MUJOCO_MCP_MAX_SESSIONSNoMax concurrent sessions16

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
mujoco_load_modelA

Load a MuJoCo model into a new simulation session. Provide exactly ONE of sample | file_path | xml_string.

Returns JSON: {session_id, source, nq, nv, nu, nsensor, nkey, timestep,
joints: [names], actuators: [names], sensors: [names], keyframes: [names]}.
The name arrays define the element order of qpos/qvel/ctrl vectors used by every other tool.
Next: mujoco_step to advance physics, mujoco_get_state to read, mujoco_model_info for ranges/types.
mujoco_model_infoA

Detailed structure of a loaded model: joint types/ranges, actuator ctrlranges, sensors, bodies, options.

Returns JSON: {session_id, source, sizes: {nq, nv, nu, na, nbody, njnt, ngeom, nsensor, nkey},
options: {timestep, gravity, integrator},
joints: [{name, type, range|null, qpos_adr, dof_adr}],
actuators: [{name, ctrlrange|null, gear}],
sensors: [{name, type, dim}], bodies: [names], keyframes: [names]}.
Use before choosing ctrl values (respect ctrlrange) or interpreting qpos/qvel layout.
mujoco_resetA

Reset a session to its initial state (or a named keyframe) and zero the step counter.

Without a keyframe, restores the configured seeded start (if any), else model defaults.
Clears force guard and runtime errors. Identical full states and control sequences
reproduce trajectories with the same model, engine and stepping schedule.
Returns the post-reset state JSON (same shape as mujoco_get_state).
mujoco_stepA

Advance the simulation. Optionally set actuator controls first; ctrl persists across later steps.

Returns the post-step state JSON: {session_id, time, steps_taken, qpos, qvel, ctrl, sensors, ...}
filtered by `include`. Batch steps in one call (e.g. nsteps=500 for 1s at timestep 0.002)
instead of many single-step calls. Errors and suggests mujoco_reset if the state diverges.
mujoco_get_stateA

Read the current state of a session without advancing physics.

Returns JSON with the requested blocks: qpos/qvel/ctrl (vectors in model order),
sensors ({name: value}), bodies ({name: {pos, quat}} world-frame), contacts
({ncon, listed, contacts: [{geom1, geom2, pos, dist, normal_force}]}, capped at 20).
mujoco_set_stateA

Overwrite parts of a session's state (qpos, qvel, ctrl, time), then recompute derived quantities.

Only provided fields change. Runs mj_forward so sensors/body poses reflect the new state
without advancing time. Returns the resulting state JSON. Useful for setting initial
conditions or visual replay. Use snapshots, not rounded state views, for exact continuation.
mujoco_list_sessionsA

List all active simulation sessions.

Returns JSON: {count, sessions: [{session_id, source, time, steps_taken, nq, nu}]}.
mujoco_close_sessionA

Close a session and free its model and data. The session_id becomes invalid immediately.

Returns JSON: {closed, remaining: [session_ids]}.
mujoco_open_viewerA

Open a native MuJoCo window sharing this session's model and state.

Starts paused; call mujoco_step or mujoco_set_running next. One window per
server: close the current viewer before displaying another session. This
opens a new controlled window; it does not attach to the standalone DMG app.
On macOS launch the server via start.sh or mjpython.
mujoco_close_viewerA

Close this session's window and pause playback, keeping its state loaded.

mujoco_set_runningA

Play/pause the visible session at approximately real-time speed.

Open a viewer first. Optional ctrl changes persist; this can update controls
during playback. Pause before deterministic mujoco_step calls. Closing the
window or resetting pauses playback. Instability pauses automatically and
appears in runtime_error; call mujoco_reset to recover.
mujoco_step_guardedA

Advance a paused session, measuring all contacts after every physics step.

Stops at the first force-limit exceedance. guard.peak_force_N is the maximum
summed contact load on body_name (including descendants); opposite contact
forces do not cancel. World-frame resultant force and torque are also returned.
The guard detects an exceedance, it cannot guarantee zero overshoot. No hard
real-time or physical safety certification is implied. A tripped session is
latched until reset or snapshot restore. Optional record_every samples a JSON
trace every N steps (0 disables; maximum 2000 frames). Initial, terminal and
trip states are always captured; peak_force_N tracks all steps, not samples.
Persist returned trace/provenance in the consuming project for replay/evidence.
mujoco_get_wrenchA

Measure ALL external contacts on a non-world body and its descendants.

Raw resultant force (N) and torque (N m) are in world axes. Torque is about
the requested body's origin. force_N sums contact magnitudes (opposing forces
do not cancel). This is contact-only, not a general wrist F/T sensor.
observed_force_xyz_N adds configured noise; raw force and guard stay unchanged.
mujoco_configure_experimentA

Configure generic trial conditions and reset to the realized seeded start.

Close viewer first. Supports named geom friction [sliding,torsional,rolling],
named explicit pair_friction [sliding1,sliding2,torsional,rolling1,rolling2],
hinge/slide initial joint_offsets and Gaussian joint_noise_std (rad/m), mocap
body poses (m, wxyz), additive ctrl_bias in actuator input units, and named
sensor_noise_std in each sensor's units. Noise affects observations only;
physical state and force guarding remain raw. Missing options return to model
defaults. Repeating the same config reproduces initial conditions. metadata
stores caller tags such as trial_id/param_version, without enforcing policy.
mujoco_get_provenanceA

Return compiled-model SHA-256, engine/server versions, code hash and experiment config.

Source label is always sim. The consuming project supplies its own strategy, parameter version and code commit; arbitrary caller tags are metadata only.

mujoco_get_snapshotA

Get unrounded mjSTATE_INTEGRATION plus step/noise counters and guard status.

Includes act, warm-start, applied forces, mocap and other integration inputs,
beyond qpos/qvel. Persist this JSON in your project. Pause before capture.
mujoco_restore_snapshotA

Restore a paused session; requires identical compiled model, config and engine version.

Restores exact integration state, step/noise counters and guard status. A snapshot taken before a force stop clears the latch; a tripped one retains it.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4.3/5.0

Scored across 17 tools

Disambiguation5/5

Each tool maps to a distinct responsibility: session lifecycle, model inspection, stepping, state access, snapshots, viewer control, contact measurement, experiment configuration, and provenance. Even the paired tools like step/step_guarded and get_state/get_snapshot are clearly separated by their exact purpose and behavior.

Naming Consistency5/5

All tools consistently use the mujoco_ prefix with a clear snake_case verb_noun pattern (load_model, get_state, close_session, set_running, restore_snapshot). There are no mixed naming conventions or vague generic verbs.

Tool Count4/5

17 tools is slightly above the typical well-scoped range, but the count is justified by the breadth of the domain: session management, physics stepping, state access, snapshot handling, viewer control, and experiment configuration. A few tools could potentially be consolidated, but none feel redundant.

Completeness5/5

The tool set covers the full simulation lifecycle: load, inspect, step, read/write state, reset, snapshot/restore, run experiments, measure contacts, and close sessions. It also includes reproducibility-oriented tools like provenance and snapshots, so agents can execute and evidence a complete MuJoCo workflow without obvious dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues