Mujoco MCP Server

MuJoCo MCP服务器

   

65个MCP工具 暴露 MuJoCo 物理模拟 克劳德代码 以及任何 模型上下文协议 客户。

加载机器人、步进物理、分析联系人、优化轨迹、导出视频——所有这些都可以通过人工智能助手中的自然语言完成。

______________________________________________________________________

需求

• Python≥3.10，MuJoCo≥2.3
• 带有EGL（GPU）或OSMesa（CPU无头）的Linux用于渲染
• 紫外线 推荐

______________________________________________________________________

快速开始

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

或手动输入 ~/.claude.json:

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

HTTP传输（远程）

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"

RL和数据管道

"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]"

启用 export_video --将任何记录的轨迹渲染为 四个 （要求 imageio[ffmpeg])或 图形交换格式 （仅提供枕头，不额外收费）。

视觉分析

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

启用 analyze_scene, compare_scenes, track_object，以及 render_figure_strip 通过Gemini 2.5 Pro。

______________________________________________________________________

环境变量

______________________________________________________________________

建筑

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

关键模式：

• 每个工具组都有一个 _XXX_impl() 同步功能（用于测试）+异步MCP包装器
• @mcp.tool() 外部装饰师， @safe_tool internal——所有异常都返回JSON错误，从不引发
• SimManager 保存命名插槽("default", "exp1"，…），每个都有模型、数据、轨迹和可选的控制器/RL环境

______________________________________________________________________

发展

# Run all tests
pytest tests/

# Single file
pytest tests/test_sim_tools.py -v

# Lint
ruff check src/mujoco_mcp

测试需要OSMesa进行无头渲染(conftest.py 套 MUJOCO_GL=osmesa 自动）。

______________________________________________________________________

贡献

欢迎捐款。一些指导方针：

• 新工具组： 创建 src/mujoco_mcp/tools/.py，注册 server.py，在中添加测试 tests/test_.py
• _impl 图案： 保持同步 _XXX_impl() 用于直接测试调用的函数；异步MCP包装器是一个薄壳
• 先测试： 在实现之前编写失败的测试
• 没有新的硬依赖关系 无需讨论——可选附加内容 pyproject.toml [project.optional-dependencies]

在启动大型功能之前打开一个问题。

______________________________________________________________________

许可证

麻省理工学院