Ros MCP

1## ROS MCP
2[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/Yutarop/ros-mcp)](https://archestra.ai/mcp-catalog/yutarop__ros-mcp)
3![ROS2-humble Industrial CI](https://github.com/Yutarop/ros-mcp/actions/workflows/ros2_humble_ci.yml/badge.svg)
4 
5**ROS MCP** is a MCP server designed for controlling robots in ROS environments using natural language. 
6It supports communication via ROS topics, services, and actions, and works with any ROS message type.
7 
8## Demo
9#### Test to see if ros topics, services, and actions can be used.
10https://github.com/user-attachments/assets/61143c37-fb73-4998-9cbc-844d92ae61d9
11 
12##### Prompt used (Topic)
13> Open gazebo with TurtleBot3 and publish topic to move it.
14 
15##### Prompt used (Service)
16> Show me service list and call service to reset the world in Gazebo.
17 
18##### Prompt used (Action)
19> Show me action list and call action to move the TurtleBot3 forward for 1m.
20 
21## Components
22- **Socket Server** ([`socket_server.py`](https://github.com/Yutarop/ros-mcp/blob/main/src/socket_server.py)): A lightweight server that runs on localhost:8765 to handle GUI-related operations. 
23It receives instructions from the MCP server to launch tools such as `Gazebo` or `rqt_graph` on the local display.
24 
25- **MCP Server** ([`ros-general.py`](https://github.com/Yutarop/ros-mcp/blob/main/ros-general.py)): A Python-based server that implements the MCP.
26It processes natural language input, maps it to ROS commands, and communicates with the socket server.
27To enable node communication between the MCP server and the local machine, both must be configured with the same `ROS_DOMAIN_ID` on the same local network.
28 
29## Overview of MCP Tools
30- `Topic Management`: List, monitor, and publish to ROS2 topics
31- `Node Control`: List and inspect running ROS2 nodes
32- `Service Interaction`: Call ROS2 services with custom
33- `Action Support`: Send goals to ROS2 actions
34- `GUI Integration`: Launch ROS2 GUI tools via WebSocket server
35- `Environment Debugging`: Check ROS2 setup and configuration
36- `Process Management`: Clean up running ROS2 processes
37 
38Please refer [here](https://github.com/Yutarop/ros-mcp/wiki/Available-Tools) for more details.
39 
40## Getting Started
41#### Requirements
42- ROS2 Humble Hawksbill (This project has only been tested with ROS2 Humble. Compatibility with other ROS2 distributions is not guaranteed.)
43- claude desktop ([Linux](https://github.com/aaddrick/claude-desktop-debian), [macOS](https://claude.ai/download) and [Windows](https://claude.ai/download))
44- Python 3.10+
45- websockets >= 15.0.1
46- uv package manager ([Installing uv](https://docs.astral.sh/uv/getting-started/installation/))
47- Other dependencies as listed in `pyproject.toml`
48 
49### Installation
50#### Git clone and install websockets package
51```bash
52git clone git@github.com:Yutarop/ros-mcp.git
53cd ros-mcp
54pip install "websockets>=15.0.1"
55```
56 
57#### Activate .venv and install dependencies
58```bash
59uv venv
60source .venv/bin/activate
61uv pip install -e .
62```
63 
64#### Claude Settings (`claude_desktop_config.json`)
65To use the MCP server correctly with Claude Desktop, you need to modify the claude_desktop_config.json file with appropriate values.
66```
67{
68  "mcpServers": {
69    "ros-general": {
70      "command": "uv",
71      "args": [
72        "--directory",
73        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcp",
74        "run",
75        "bash",
76        "-c",
77        "export ROS_LOG_DIR=/tmp && export ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-YOUR_ROS_DOMAIN_ID} && source /opt/ros/humble/setup.bash && python3 /ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-general.py"
78      ]
79    }
80  }
81}
82```
83##### **💡 Replace the following placeholders:**
84- `/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcp`
85Replace with the absolute path the ros-mcp directory. 
86For example: /home/ubuntu/ros-mcp
87 
88- `YOUR_ROS_DOMAIN_ID`
89  Replace with the ROS domain ID used in your environment to enable ROS communication between the MCP server and your local machine. If you're not sure what your current domain ID is, you can check it by running the following command in your terminal:
90  ```bash
91  echo $ROS_DOMAIN_ID
92  ```
93  If nothing is printed, the domain ID is not set, and the default value 0 will be used.
94  Alternatively, you can set it manually using the following command:
95  ```bash
96  export ROS_DOMAIN_ID=10  # Replace 10 with your desired domain ID
97  ```
98- `/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-general.py`
99Replace with the absolute path to your ros-general.py script.
100For example: /home/ubuntu/ros-mcp/ros-general.py
101 
102## Running the Servers
103#### Start MCP server
104Make sure your virtual environment is activated before running the MCP server:
105```bash
106(ros-mcp) $ uv run ros-general.py
107```
108#### Start socket server
109```bash
110python3 socket_server.py
111```
112 > 💡not in the virtual environment!
113 
114