unitree-go2

The Unitree Go2 MCP Server provides a natural language interface to control a Unitree Go2 robot by translating user commands into ROS 2 instructions. Using an LLM, the server interprets plain language requests (for example, make the Go2 move forward, turn, or perform obstacle avoidance) and converts them into the corresponding ROS 2 topics, services, and actions that drive the robot. The system expects that the Unitree Go2 is reachable on the network and that the ROS 2 environment is properly set up (as described in the installation steps). Once running, you can issue natural language commands through your chosen AI system, and the MCP server will generate and publish the appropriate ROS 2 commands to operate the robot.

Typical workflow:

• Ensure the Unitree ROS 2 setup is complete and the robot is network-connected.
• Start the MCP server (via uv) with the proper directory and server.py path.
• Use any AI system capable of generating natural language instructions that integrates with MCP, feeding it commands like “Move forward at 0.5 m/s for 3 seconds” or “Rotate left 45 degrees while maintaining position.”
• The server translates each prompt into ROS 2 messages, drives the Go2 accordingly, and you can observe topic activity or robot feedback to confirm actions.

Prerequisites:

• A Unitree Go2 robot and a compatible ROS 2 environment installed on Ubuntu (Humble or Foxy recommended).
• Git installed on your machine.
• Python and uv (the uv runtime) available on your system.
• Access to the repository where this MCP server lives.

Installation steps:

1. Install ROS 2 and set up your Unitree ROS 2 environment according to the Unitree ROS 2 guidance (as referenced in the README).
2. Clone this MCP server repository and navigate into it:

git clone https://github.com/lpigeon/unitree-go2-mcp-server.git
cd unitree-go2-mcp-server

3. Install uv (Python package runner) if not already installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or, alternatively:

pip install uv

4. (Optional) Create and activate a virtual environment for Python dependencies:

uv venv
source .venv/bin/activate

5. Prepare the MCP configuration file (mcp.json) with the required command and arguments as shown in the example. Update the absolute path in the directory argument to point to the local copy of this repository. Ensure the Unitree ROS 2 setup path is correct in the environment variables if used by the server.
6. Run the MCP server using uv with the configured directory and server script:

uv run /ABSOLUTE/PATH/TO/PARENT/FOLDER/unitree-go2-mcp-server run server.py

7. Verify connectivity to the Go2 robot and ROS 2 topics (e.g., ros2 topic list) to ensure the robot is visible on the network.

Tips and common issues:

• Ensure the Unitree ROS 2 environment is fully set up and that the Go2 is connected to the same network as the machine running the MCP server.
• If you encounter ROS 2 topic visibility issues, double-check the Go2 network connection and the ROS 2 environment setup scripts referenced in UNITREE_ROS2_SETUP_SH_PATH.
• The MCP server expects a correctly formatted mcp.json with the command and directory path. Use absolute paths to avoid directory resolution issues.
• If you plan to use rosbridge, you may need to configure LOCAL_IP, ROSBRIDGE_IP, and ROSBRIDGE_PORT in the server environment to enable the bridge connection.
• When debugging, view ROS topic activity (ros2 topic list, ros2 topic echo) to confirm the translated commands are being published as expected.