git clone https://github.com/Rongxuan-Zhou/mujoco-mcp-server.git
cd mujoco-mcp-server
pip install -e .

claude mcp add mujoco-sim -- uv run --directory /path/to/mujoco-mcp-server mujoco-mcp

{
  "mcpServers": {
    "mujoco-sim": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mujoco-mcp-server", "mujoco-mcp"],
      "env": { "MUJOCO_GL": "egl" }
    }
  }
}

python -m mujoco_mcp --transport streamable-http --host 0.0.0.0 --port 8080

"Run iLQR on the Franka arm to reach [0.4, 0, 0.5] in 50 steps — show the control sequence and waypoints"
"Compare MPPI (200 samples) vs iLQR on the hopper reaching task; which converges to lower cost?"
"Plan a min-jerk Cartesian trajectory for the end-effector, step the PD controller, and plot joint torques over time"

"Sweep body mass ±40% and floor friction [0.1, 2.0] over 50 random samples — report mean/std of max CoM speed"
"Apply 30 N lateral impulses across 16 Fibonacci sphere directions; what is the stability margin of the current controller?"
"At what force magnitude does the bipedal walker fail to recover in more than 25% of directions?"

"Validate this MJCF for dangling actuators and solref instabilities before I load it"
"Are the contact parameters between the gripper fingers and the object causing numerical stiffness? Suggest alternatives"
"Show the active contact forces and check whether the friction cone constraints are satisfied"

"Compute the manipulability index at this Franka configuration — is it near a singularity?"
"Solve IK for site 'ee' at [0.5, 0.2, 0.3] and verify the joint limits are respected"
"Map reachable workspace by sweeping joint angles and recording Cartesian ee positions"

"Set up a Gymnasium env for the hopper, run 500 steps with random actions, and export a phase portrait of hip angle vs angular velocity"
"Record a 10-second rollout, export full state log with body positions and sensor data, then plot the 3D CoM trajectory"
"Run domain randomization on link masses and timestep — export CSV and show which parameter range produces the worst instability"

pip install -e ".[media]"

pip install -e ".[vision]"
export GEMINI_API_KEY=your_key

src/mujoco_mcp/
├── server.py           # FastMCP app + lifespan context
├── sim_manager.py      # Multi-slot simulation manager (thread-safe)
├── _registry.py        # FastMCP instance (avoids circular imports)
├── constants.py        # Shared constants (yield intervals, thresholds)
├── tools/              # All @mcp.tool() registrations (one file per group)
├── resources.py        # MCP Resources
├── prompts.py          # MCP Prompts (7 workflow prompts)
└── utils/
    └── gl_setup.py     # Probe EGL → OSMesa; sets MUJOCO_GL before mujoco import

# Run all tests
pytest tests/

# Single file
pytest tests/test_sim_tools.py -v

# Lint
ruff check src/mujoco_mcp