Unitree Go2 MCP Server

1# Unitree Go2 MCP Server
2![ROS 2](https://img.shields.io/badge/ROS_2-Foxy|Humble-blue)
3![Static Badge](https://img.shields.io/badge/License-Apache2.0-green)
4 
5<center><img src="https://github.com/lpigeon/unitree-go2-mcp-server/blob/main/img/thumbnail.png" width="800"/></center>
6 
7The **Unitree Go2 MCP Server** is a server built on the Model Context Protocol (MCP) that enables users to control the Unitree Go2 robot using natural language commands interpreted by a Large Language Model (LLM). These commands are translated into ROS2 instructions, allowing the robot to perform corresponding actions.
8 
9<a href="https://glama.ai/mcp/servers/@lpigeon/unitree-go2-mcp-server">
10  <img width="380" height="200" src="https://glama.ai/mcp/servers/@lpigeon/unitree-go2-mcp-server/badge" alt="Unitree Go2 Server MCP server" />
11</a>
12 
13## Requirements
14 
15- **Unitree Go2 robot**
16- **Ubuntu 20.04 or 22.04**
17- **ROS2 environment** : [Humble](https://docs.ros.org/en/humble/Installation.html)(recommended) or [Foxy](https://docs.ros.org/en/foxy/Installation.html)
18 
19## MCP Functions
20 
21You can find the list of functions in the [MCPFUNCTIONS.md](MCPFUNCTIONS.md).
22 
23## Installation
24 
25### 1. Setup `unitree_ros2` environment
26 
27https://github.com/unitreerobotics/unitree_ros2
28 
29- **You need to complete the setup up to `Step 2: Connect and test` in the repository linked above.**
30 
31### 2. Clone this repository
32 
33```bash
34git clone https://github.com/lpigeon/unitree-go2-mcp-server.git
35cd unitree-go2-mcp-server
36```
37 
38### 3. `uv` Installation
39- To install `uv`, you can use the following command:
40```bash
41curl -LsSf https://astral.sh/uv/install.sh | sh
42```
43or
44```bash
45pip install uv
46```
47 
48- Create virtual environment and activate it (Optional)
49```bash
50uv venv
51source .venv/bin/activate
52```
53 
54### 4. MCP Server Configuration
55Set MCP setting to mcp.json.
56 
57**Please keep in mind that the configuration must be done on the PC connected to the Go2.**
58 
59```bash
60{
61    "mcpServers": {
62        "unitree-go2-mcp-server": {
63            "command": "uv",
64            "args": [
65              "--directory",
66              "/ABSOLUTE/PATH/TO/PARENT/FOLDER/unitree-go2-mcp-server",
67              "run",
68              "server.py"
69            ]
70        }
71    }
72}
73```
74 
75If you use Claude Desktop, you can find mcp.json using the following command:
76 
77- MacOS
78```bash
79code ~/Library/Application\ Support/Claude/claude_desktop_config.json
80```
81 
82- Linux(Ubuntu)
83  
84You can install Claude Desktop to use [claude-desktop-debian](https://github.com/aaddrick/claude-desktop-debian).
85 
86```bash
87code ~/.config/Claude/claude_desktop_config.json
88```
89 
90- Windows
91```bash
92code $env:AppData\Claude\claude_desktop_config.json
93```
94 
95## How To Use
96### 1. Set `UNITREE_ROS2_SETUP_SH_PATH`.
97- Open `server.py` and change your `UNITREE_ROS2_SETUP_SH_PATH` (eg. `/home/lpigeon/unitree_ros2/setup.sh`)
98 
99#### If you use `rosbridge`, you need Set IP and Port to connect rosbridge (Optional).
100- Open `server.py` and change your `LOCAL_IP`, `ROSBRIDGE_IP` and `ROSBRIDGE_PORT`. (`ROSBRIDGE_PORT`'s default value is `9090`)
101 
102### 2. Check the Go2 robot is connected to the network.
103Type the following command in the terminal.
104```bash
105ros2 topic list
106```
107You should see the following topic:
108```bash
109/wirelesscontroller
110```
111**If you don't see the topic, check the connection between the Go2 robot and the network.**
112 
113### 3. Run any AI system that has imported `unitree-go2-mcp-server`.
114 
115### 4. Type "Make the Go2 robot move forward at a velocity of 0.5 m/s for 3 seconds.".
116 
117<center><img src="https://github.com/lpigeon/unitree-go2-mcp-server/blob/main/img/how_to_use_1.png" width="500"/></center>
118 
119### 5. Check the Go2 robot's movement.
120 
121<center><img src="https://github.com/lpigeon/unitree-go2-mcp-server/blob/main/img/how_to_use_2.gif" width="500"/></center>
122 
123### 6. Type what you want to do and Enjoy!
124 
125## Contextual Understanding
126When you type a command like "It looks like the Go2 is getting tired," the LLM interprets this contextually — understanding that the robot might need a break or some form of stretching!
127 
128<center><img src="https://github.com/lpigeon/unitree-go2-mcp-server/blob/main/img/contextual_understanding.gif" width="800"/></center>
129 
130## Simple Task
131This task is a comprehensive demo task showcasing the Unitree Go2 robot's obstacle avoidance, direction changing, and user interaction capabilities.
132 
133<center><img src="https://github.com/lpigeon/unitree-go2-mcp-server/blob/main/img/task_test.gif" width="800"/></center>
134 
135## Contributing
136Contributions are welcome!  
137Whether you're fixing a typo, adding a new function, or suggesting improvements, your help is appreciated.  
138Please follow the [contributing guidelines](CONTRIBUTING.md) for more details on how to contribute to this project.
139