unitree-sdk2-mcp

🌐 English | 中文

ROSClaw MCP Server for Unitree Robots via DDS protocol.

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 control any Unitree robot through the Model Context Protocol. It communicates with the robot using DDS (Data Distribution Service) — the same protocol used by Unitree's official SDK.

LLM Agent  ──MCP──►  unitree-sdk2-mcp  ──DDS──►  Unitree Robot

Supported Robots

| Model | Type | DOF | Features | Weight | Battery | |-------|------|-----|----------|--------|---------| | G1 | Humanoid | 23 | Walking, Arm Control | ~35kg | 2.5h | | Go2 | Quadruped | 12 | Trotting, Galloping | ~15kg | 2.0h | | Go2w | Quadruped+Wheels | 12 | Hybrid Locomotion | ~16kg | 2.0h | | H1 | Humanoid | 20 | Walking, Arm Control | ~47kg | 2.0h | | H2 | Humanoid | 20 | Walking, Arm Control | ~45kg | 2.5h | | B2 | Quadruped | 12 | Industrial, Heavy Payload | ~60kg | 4.0h | | B2w | Quadruped+Wheels | 12 | Industrial+Wheels | ~62kg | 4.0h | | A2 | Quadruped | 12 | Agile, Education | ~15kg | 1.5h | | R1 | Wheeled | 4 | Navigation, Delivery | ~25kg | 3.0h |

SDK Information

| Property | Value | |----------|-------| | SDK Name | unitree_sdk2 | | SDK Version | 2.1.0+ | | Protocol | DDS (Data Distribution Service) | | Source Repository | github.com/unitreerobotics/unitree_sdk2 | | Documentation | support.unitree.com | | License | BSD-3-Clause | | Generated | 2026-04-15 |

Features

• Multi-Robot Support: Control any Unitree robot with unified interface
• Dynamic Configuration: Automatic robot type detection and configuration
• High-Level Actions: Stand, sit, walk, wave (robot-dependent)
• Safety Guards: Joint limits enforced before every command
• Real-time State: Battery, mode, joint positions, IMU at 100Hz
• DDS Protocol: CycloneDDS / FastDDS compatible
• Async Design: Non-blocking MCP tools with background state thread

Installation

# Clone
git clone https://github.com/ros-claw/unitree-sdk2-mcp.git
cd unitree-sdk2-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

# Required: Unitree SDK2
# Download from: https://github.com/unitreerobotics/unitree_sdk2

# DDS Middleware (choose one)
pip install cyclonedds  # or fastdds

Quick Start

Run as MCP Server

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

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

# Legacy alias (backward compatible)
rosclaw-g1-mcp

Connect to a Robot

# First, list available robots
list_robots()

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

# Connect
connect_robot(robot_id="g1", domain_id=0)

# Or connect to Go2
connect_robot(robot_id="go2", domain_id=0)

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unitree-sdk2": {
      "command": "python",
      "args": ["/path/to/unitree-sdk2-mcp/src/unitree_sdk2_mcp_server.py"],
      "transportType": "stdio",
      "description": "Unitree Multi-Robot via DDS",
      "sdk_version": "2.1.0",
      "sdk_source": "https://github.com/unitreerobotics/unitree_sdk2"
    }
  }
}

MCP Inspector (Testing)

mcp dev src/unitree_sdk2_mcp_server.py

Available Tools

Multi-Robot Tools

| Tool | Description | |------|-------------| | list_robots | List all supported Unitree robots | | get_robot_info | Get configuration for specific robot | | connect_robot | Connect to a robot (specify robot_id) | | disconnect_robot | Disconnect from a robot |

Control Tools

| Tool | Description | Supported Robots | |------|-------------|------------------| | stand_up | Command robot to stand up | G1, H1, H2, Go2, B2, A2 | | sit_down | Command robot to sit down/stop | All | | walk_with_velocity | Walk with linear/angular velocity | G1, Go2, H1, H2, B2, A2 | | move_joint | Move a single joint to target angle | All with joints | | move_joints | Move multiple joints simultaneously | All with joints | | stop_movement | Stop and hold current position | All | | emergency_stop | Emergency halt (use with caution!) | All | | wave_hand | Perform waving gesture | G1, H1, H2 |

Available Resources

| Resource | Description | |----------|-------------| | unitree://{robot_id}/status | Battery, mode, joint positions | | unitree://{robot_id}/joints | Joint limits for all joints | | unitree://connections | All active DDS connections |

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

G1 Joint Limits:

| Joint | Range (rad) | |-------|-------------| | left_hip_yaw | [-2.35, 2.35] | | left_hip_roll | [-0.78, 0.78] | | left_hip_pitch | [-2.5, 2.5] | | left_knee | [-0.5, 2.5] | | left_ankle | [-1.0, 1.0] | | right_hip_yaw | [-2.35, 2.35] | | right_hip_roll | [-0.78, 0.78] | | right_hip_pitch | [-2.5, 2.5] | | right_knee | [-0.5, 2.5] | | right_ankle | [-1.0, 1.0] | | waist_yaw | [-2.5, 2.5] | | waist_roll | [-0.5, 0.5] | | waist_pitch | [-1.0, 1.0] | | left_shoulder_pitch | [-3.14, 3.14] | | left_shoulder_roll | [-0.5, 3.5] | | left_shoulder_yaw | [-2.0, 2.0] | | left_elbow | [-1.5, 2.0] | | right_shoulder_pitch | [-3.14, 3.14] | | right_shoulder_roll | [-3.5, 0.5] | | right_shoulder_yaw | [-2.0, 2.0] | | right_elbow | [-1.5, 2.0] |

Quadruped Robots (Go2, Go2w, B2, B2w, 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 ``

Go2 Joint Limits:

| Joint | Range (rad) | |-------|-------------| | front_left_hip | [-0.87, 0.87] | | front_left_thigh | [-0.52, 2.97] | | front_left_calf | [-2.76, -0.52] | | ... (similar for other legs) |

Safety Information

WARNING: This MCP server controls physical robots. Improper use can cause:

• Equipment damage
• Personal injury
• Property damage

Safety Features

| Feature | Description | |---------|-------------| | Joint Limits | All commands validated against hardware limits per robot type | | Velocity Limits | Enforced per robot configuration | | Emergency Stop | emergency_stop() disables motors immediately |

Safety Levels

| Level | Color | Description | |-------|-------|-------------| | CRITICAL | 🔴 | Immediate danger (falling, collision) | | HIGH | 🟠 | Potential hardware damage | | MEDIUM | 🟡 | Operational issue | | LOW | 🟢 | Informational |

Emergency Procedures

1. Immediate Stop: Use emergency_stop(robot_id) or press physical E-stop
2. Power Off: Disconnect battery if safe
3. Check Status: Use unitree://{robot_id}/status resource

Error Handling

Error Codes

| Code | Name | Severity | Description | |------|------|----------|-------------| | -1 | CONNECTION_FAILED | 🟠 error | Failed to connect to DDS domain | | -2 | TIMEOUT | 🟠 error | Operation timed out | | -3 | INVALID_PARAMETER | 🟠 error | Invalid joint name or value | | -4 | SAFETY_VIOLATION | 🔴 critical | Command exceeds joint limits | | -5 | NOT_INITIALIZED | 🟠 error | Not connected to robot | | -6 | UNKNOWN_ROBOT | 🟠 error | Unsupported robot ID |

Troubleshooting

| Issue | Possible Cause | Solution | |-------|---------------|----------| | Connection failed | Robot powered off | Check battery and power switch | | Connection failed | Wrong DDS domain | Verify domain_id parameter | | Command rejected | Joint limit exceeded | Check robot-specific joint limits | | Slow response | Network latency | Check WiFi/Ethernet connection | | Unknown robot ID | Typo in robot_id | Use list_robots() to see valid IDs |

Architecture

unitree_sdk2_mcp_server.py
├── SDK_METADATA        — SDK version and source info
├── RobotState          — Robot state dataclass (generic)
├── StateBuffer         — Thread-safe ring buffer for DDS data
├── UnitreeDDSBridge    — DDS communication bridge
│   ├── connect()       — Initialize DDS participant
│   ├── _dds_listener() — Background thread at 100Hz
│   └── publish_command() — Send /lowcmd
├── robot_configs.py    — Configuration for all 9 robots
│   ├── G1_CONFIG       — G1 humanoid (23 DOF)
│   ├── GO2_CONFIG      — Go2 quadruped (12 DOF)
│   ├── H1_CONFIG       — H1 humanoid (20 DOF)
│   ├── B2_CONFIG       — B2 industrial quadruped
│   ├── A2_CONFIG       — A2 agile quadruped
│   └── R1_CONFIG       — R1 wheeled robot
└── MCP Tools           — FastMCP tool definitions

DDS Topics

| Topic | Direction | Description | |-------|-----------|-------------| | /lowstate | Subscribe | Robot state (joints, IMU, battery) | | /lowcmd | Publish | Robot commands (joint targets, mode) | | /sportmodestate | Subscribe | Sport mode state |

Dependencies

• Python 3.10+
• mcp[fastmcp] — MCP framework
• unitree_sdk2 — Unitree DDS SDK (install separately from hardware package)
• cyclonedds or fastdds — DDS middleware

References

• Unitree SDK2 GitHub
• Unitree Developer Docs
• Unitree G1 Product Page
• Unitree Go2 Product Page
• DDS Specification
• MCP Protocol

License

MIT License — See LICENSE

Part of ROSClaw

• rosclaw — Core framework (see arXiv paper)
• unitree-sdk2-mcp — Unitree Multi-Robot (DDS)
• rosclaw-ur-ros2-mcp — UR5 arm (ROS2)
• rosclaw-gimbal-mcp — GCU Gimbal (Serial)
• rosclaw-ur-rtde-mcp — UR5 via RTDE

---

Generated by ROSClaw SDK-to-MCP Transformer

SDK Version: unitree_sdk2 2.1.0+ | Protocol: DDS | Robots: G1, Go2, Go2w, H1, H2, B2, B2w, A2, R1