unitree-mujoco-mcp

English | 中文

ROSClaw MCP Server for Unitree Robots via MuJoCo Simulation.

Supports: G1, Go2, Go2w, H1, H2, B2, B2w, A2, R1

Part of the ROSClaw Embodied Intelligence Operating System.

Overview

This MCP server enables LLM agents (Claude, GPT-4, etc.) to simulate and control Unitree robots through the Model Context Protocol. It uses MuJoCo physics simulation to provide a safe, virtual environment for robot development and testing.

LLM Agent ──MCP──► unitree-mujoco-mcp ──MuJoCo──► Simulated Robot

Features

• Multi-Robot Support: Simulate any Unitree robot (G1, Go2, H1, B2, A2, R1)
• Realistic Physics: High-fidelity MuJoCo simulation with accurate dynamics
• Visual Rendering: Interactive 3D visualization of robot state
• Control Interface: Position control, torque control, and joint-level commands
• State Monitoring: Real-time joint positions, velocities, and body pose
• Sim-to-Real Ready: Compatible with unitree_sdk2 API for easy transition

Supported Robots

| Model | Type | DOF | Features | MJCF Scene | |-------|------|-----|----------|------------| | G1 | Humanoid | 23 | Walking, Arm Control | g1/scene.xml | | Go2 | Quadruped | 12 | Trotting, Galloping | go2/scene.xml | | Go2w | Quadruped+Wheels | 12 | Hybrid Locomotion | go2w/scene.xml | | H1 | Humanoid | 20 | Walking, Arm Control | h1/scene.xml | | H2 | Humanoid | 20 | Walking, Arm Control | h1/scene.xml | | B2 | Quadruped | 12 | Industrial, Heavy Payload | b2/scene.xml | | B2w | Quadruped+Wheels | 12 | Industrial+Wheels | b2w/scene.xml | | A2 | Quadruped | 12 | Agile, Education | go2/scene.xml | | R1 | Wheeled | 4 | Navigation, Delivery | r1/scene.xml |

Installation

Prerequisites

1. MuJoCo (automatically installed via pip)
2. Unitree MuJoCo Models: Clone the unitree_mujoco repository

# Clone unitree_mujoco for robot models
git clone https://github.com/unitreerobotics/unitree_mujoco.git

# Clone this MCP server
git clone https://github.com/ros-claw/unitree-mujoco-mcp.git
cd unitree-mujoco-mcp

# Install with uv (recommended)
uv venv --python python3.10
source .venv/bin/activate
uv pip install -e .

# Or with pip
pip install -e .

Dependencies

# Core dependencies (auto-installed)
pip install mujoco>=3.0.0 numpy>=1.24.0 mcp[fastmcp]

# Optional: For sim-to-real testing with unitree_sdk2
pip install unitree_sdk2_python

Quick Start

Run as MCP Server

# stdio transport (for Claude Desktop / MCP clients)
python src/unitree_mujoco_mcp_server.py

# Or using the installed entry point
unitree-mujoco-mcp

Start a Simulation

# List available robots
list_robots()

# Get robot info
get_robot_info(robot_id="g1")

# Start simulation with visualization
start_simulation(robot_id="g1", render=True)

# Or start Go2 simulation
start_simulation(robot_id="go2", render=True)

Control the Robot

# Set specific joint positions
set_joint_positions(
    robot_id="g1",
    positions={
        "left_shoulder_pitch": -1.57,
        "left_elbow": -1.0
    },
    duration=2.0
)

# Apply raw control values
apply_control(robot_id="g1", controls=[0.0] * 23)

# Pause/Resume simulation
pause_simulation(robot_id="g1")
resume_simulation(robot_id="g1")

# Reset simulation
reset_simulation(robot_id="g1")

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unitree-mujoco": {
      "command": "python",
      "args": ["/path/to/unitree-mujoco-mcp/src/unitree_mujoco_mcp_server.py"],
      "transportType": "stdio",
      "description": "Unitree MuJoCo Simulation"
    }
  }
}

Available Tools

Simulation Management

| Tool | Description | |------|-------------| | list_robots | List all supported robots | | get_robot_info | Get robot configuration | | start_simulation | Start MuJoCo simulation | | stop_simulation | Stop simulation | | reset_simulation | Reset to initial state | | pause_simulation | Pause physics | | resume_simulation | Resume physics |

Control Tools

| Tool | Description | |------|-------------| | set_joint_positions | Set joint positions | | apply_control | Apply raw control values | | get_simulation_time | Get current sim time |

Available Resources

| Resource | Description | |----------|-------------| | mujoco://{robot_id}/status | Simulation status, body position | | mujoco://{robot_id}/joints | Joint limits and info | | mujoco://simulations | All active simulations |

Robot Configuration

Humanoid Robots (G1, H1, H2)

Joint Structure:

Left Leg:   left_hip_yaw, left_hip_roll, left_hip_pitch, left_knee, left_ankle
Right Leg:  right_hip_yaw, right_hip_roll, right_hip_pitch, right_knee, right_ankle
Waist:      waist_yaw, waist_roll, waist_pitch (G1: 3 DOF, H1/H2: 1 DOF)
Left Arm:   left_shoulder_pitch, left_shoulder_roll, left_shoulder_yaw, left_elbow
Right Arm:  right_shoulder_pitch, right_shoulder_roll, right_shoulder_yaw, right_elbow

Quadruped Robots (Go2, B2, A2)

Joint Structure:

Front Left:  front_left_hip, front_left_thigh, front_left_calf
Front Right: front_right_hip, front_right_thigh, front_right_calf
Rear Left:   rear_left_hip, rear_left_thigh, rear_left_calf
Rear Right:  rear_right_hip, rear_right_thigh, rear_right_calf

MJCF Model Paths

By default, the server looks for MJCF files in these locations:

1. /path/to/unitree_mujoco/unitree_robots/{robot}/scene.xml
2. ./unitree_mujoco/unitree_robots/{robot}/scene.xml
3. Custom path via mjcf_path parameter

Example custom path:

start_simulation(
    robot_id="g1",
    render=True,
    mjcf_path="/custom/path/to/g1/scene.xml"
)

Architecture

unitree_mujoco_mcp_server.py
├── SDK_METADATA        — Simulator version and info
├── SimState            — Simulation state dataclass
├── StateBuffer         — Thread-safe state buffer
├── UnitreeMuJoCoSim    — MuJoCo simulation manager
│   ├── load_model()    — Load MJCF
│   ├── start()         — Start sim thread
│   ├── _simulation_loop() — Physics loop
│   └── set_joint_positions() — Control interface
├── robot_configs.py    — Robot configurations
└── MCP Tools           — FastMCP tool definitions

Sim-to-Real Development

This simulator is designed for sim-to-real transfer:

1. Develop in Simulation: Test controllers safely in MuJoCo
2. Validate with SDK: Use same API as unitree_sdk2
3. Deploy to Real Robot: Transfer validated code to physical robot

Example workflow:

# Simulation development
start_simulation(robot_id="go2", render=True)
# ... develop and test controller ...

# Real robot deployment (with unitree-sdk2-mcp)
connect_robot(robot_id="go2", domain_id=0)
# ... same controller code ...

Dependencies

• Python 3.10+
• mcp[fastmcp] — MCP framework
• mujoco>=3.0.0 — Physics simulation
• numpy>=1.24.0 — Numerical computing
• unitree_mujoco — Robot MJCF models (external)

References

• Unitree MuJoCo GitHub
• MuJoCo Documentation
• Unitree SDK2
• MCP Protocol

License

MIT License — See LICENSE

Part of ROSClaw

• rosclaw — Core framework
• unitree-sdk2-mcp — Real robot control
• unitree-mujoco-mcp — Simulation (this repo)

Generated by ROSClaw SDK-to-MCP Transformer

Simulator: MuJoCo | Based on: unitree_mujoco | Robots: G1, Go2, Go2w, H1, H2, B2, B2w, A2, R1