wehub-resource-sync
db1d565b64
3.1 KiB
Installation Guide
The ROS-MCP server lets any MCP-compatible AI assistant control a robot running ROS — even from a different machine on the network.
Setup spans two machines on the same local network (or one machine if your AI client runs alongside ROS on the same hardware). A VPN is a great option for connecting over the internet.
| Machine | What to install | Prerequisites | Purpose |
|---|---|---|---|
| Your machine (laptop/desktop) | An AI client + the ROS-MCP server | An account with an AI provider (e.g., Claude, Codex, Gemini) | Runs the language model and the MCP server |
| The robot's machine | rosbridge | ROS installed | Bridges ROS over WebSocket for the MCP server to connect to |
Follow the three steps below to get up and running. Each step includes quick inline commands and a link to a more detailed guide.
Step 1: Set Up Your AI Client
Quick setup with Claude Code:
# On your machine:
# 1.1. Install uv (Python package runner)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 1.2. Add the MCP server to Claude Code
claude mcp add ros-mcp -- uvx ros-mcp --transport=stdio
For detailed instructions or to set up a different AI client, follow the guide for your client below.
| Client | Description | Guide |
|---|---|---|
| Claude Code (Recommended) | Anthropic's CLI for Claude | Setup guide |
| Codex CLI | OpenAI's CLI agent | Setup guide |
| Gemini CLI | Google's CLI for Gemini | Setup guide |
| Claude Desktop | Anthropic's desktop app | Setup guide |
| ChatGPT | OpenAI's desktop app | Setup guide |
| Cursor | AI-powered IDE | Setup guide |
| Robot MCP Client | Lightweight terminal client | Setup guide |
| Custom / Programmatic | Python MCP SDK | Setup guide |
Step 2: Set Up Rosbridge on the Robot
Install and launch rosbridge on the machine where ROS is running. See the Step 2: Rosbridge setup guide for detailed instructions. Quick setup below:
# On the robot:
# 2.1. Install Rosbridge
sudo apt update
sudo apt install ros-<your ros distro>-rosbridge-server
# 2.2. Launch Rosbridge
source /<path to ros WS>/install/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml
Step 3: Connect to Your Robot
See the Step 3: Connect and explore guide for connecting to your robot and sample commands. For a quick start, launch your AI assistant and type:
Connect to the robot on <ip address> and tell me what topics and services you see.
Additional Resources
- Troubleshooting — common issues and debug commands
- Examples — tutorials for turtlesim, Unitree Go2, LIMO, TurtleBot3, and more
- ROS-MCP Demos — advanced demos with simulated robots in Gazebo