wehub-resource-sync
db1d565b64
Integration Tests / melodic (push) Has been cancelled
Integration Tests / noetic (push) Has been cancelled
Integration Tests / humble (push) Has been cancelled
Integration Tests / jazzy (push) Has been cancelled
Ruff Lint & Format / ruff (push) Has been cancelled
Sync main to develop / Check if sync is needed (push) Has been cancelled
Sync main to develop / Sync main to develop (push) Has been cancelled
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# Installation Guide
|
|
|
|
The ROS-MCP server lets any [MCP-compatible](https://modelcontextprotocol.io/) 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:
|
|
|
|
```bash
|
|
# 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](clients/claude-code.md) |
|
|
| Codex CLI | OpenAI's CLI agent | [Setup guide](clients/codex-cli.md) |
|
|
| Gemini CLI | Google's CLI for Gemini | [Setup guide](clients/gemini-cli.md) |
|
|
| Claude Desktop | Anthropic's desktop app | [Setup guide](clients/claude-desktop.md) |
|
|
| ChatGPT | OpenAI's desktop app | [Setup guide](clients/chatgpt.md) |
|
|
| Cursor | AI-powered IDE | [Setup guide](clients/cursor.md) |
|
|
| Robot MCP Client | Lightweight terminal client | [Setup guide](clients/robot-mcp-client.md) |
|
|
| Custom / Programmatic | Python MCP SDK | [Setup guide](clients/custom-client.md) |
|
|
|
|
## 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](rosbridge.md) for detailed instructions. Quick setup below:
|
|
|
|
```bash
|
|
# On the robot:
|
|
# 2.1. Install Rosbridge
|
|
sudo apt update
|
|
sudo apt install ros-<your ros distro>-rosbridge-server
|
|
```
|
|
```bash
|
|
# 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](connect.md) 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](troubleshooting.md) — common issues and debug commands
|
|
- [Examples](../../examples/) — tutorials for turtlesim, Unitree Go2, LIMO, TurtleBot3, and more
|
|
- [ROS-MCP Demos](https://github.com/robotmcp/demos-ros-mcp-server) — advanced demos with simulated robots in Gazebo
|