# Unitree Mujoco Mcp

> MuJoCo simulation MCP server for Unitree robots (G1, Go2, H1, B2, A2, R1)

- **Type:** MCP server
- **Install:** `agentstack add mcp-ros-claw-unitree-mujoco-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ros-claw](https://agentstack.voostack.com/s/ros-claw)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ros-claw](https://github.com/ros-claw)
- **Source:** https://github.com/ros-claw/unitree-mujoco-mcp

## Install

```sh
agentstack add mcp-ros-claw-unitree-mujoco-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# unitree-mujoco-mcp

**English** | [中文](./README.zh.md)

ROSClaw MCP Server for **Unitree Robots** via MuJoCo Simulation.

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

Part of the [ROSClaw](https://github.com/ros-claw) 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

```bash
# 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

```bash
# 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

```bash
# 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

```python
# 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

```python
# 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`:

```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:
```python
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:
```python
# 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](https://github.com/unitreerobotics/unitree_mujoco)
- [MuJoCo Documentation](https://mujoco.readthedocs.io/)
- [Unitree SDK2](https://github.com/unitreerobotics/unitree_sdk2)
- [MCP Protocol](https://modelcontextprotocol.io/)

## License

MIT License — See [LICENSE](LICENSE)

## Part of ROSClaw

- [rosclaw](https://github.com/ros-claw/rosclaw) — Core framework
- [unitree-sdk2-mcp](https://github.com/ros-claw/unitree-sdk2-mcp) — Real robot control
- [unitree-mujoco-mcp](https://github.com/ros-claw/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*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ros-claw](https://github.com/ros-claw)
- **Source:** [ros-claw/unitree-mujoco-mcp](https://github.com/ros-claw/unitree-mujoco-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ros-claw-unitree-mujoco-mcp
- Seller: https://agentstack.voostack.com/s/ros-claw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.