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

Immediate Stop: Use emergency_stop(robot_id) or press physical E-stop
Power Off: Disconnect battery if safe
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

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