ROS MCP
Control robots in ROS2 environments with natural language via topics, services, and actions.
Add to your client
Copy the config for your MCP client and paste it into its config file.
git clone git@github.com:Yutarop/ros-mcp.git && cd ros-mcp && uv venv && source .venv/bin/activate && uv pip install -e .Paste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ros-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcp",
"run",
"bash",
"-c",
"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"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- ROS2 Humble Hawksbill (other ROS2 distributions not guaranteed)
- Claude Desktop (Linux/macOS/Windows)
- Python 3.10+
- websockets >= 15.0.1
- uv package manager
About ROS MCP
ROS MCP lets an AI assistant control robots in ROS2 environments using natural language. It exposes ROS2 topics, services, and actions through MCP tools and works with any ROS message type. A separate socket server on localhost:8765 launches GUI tools like Gazebo and rqt_graph on the local display. Both the MCP server and local machine must use the same ROS_DOMAIN_ID on the same network. Tested only with ROS2 Humble.
Tools & capabilities (7)
Topic ManagementList, monitor, and publish to ROS2 topics.
Node ControlList and inspect running ROS2 nodes.
Service InteractionCall ROS2 services with custom requests.
Action SupportSend goals to ROS2 actions.
GUI IntegrationLaunch ROS2 GUI tools (e.g. Gazebo, rqt_graph) via the WebSocket socket server.
Environment DebuggingCheck ROS2 setup and configuration.
Process ManagementClean up running ROS2 processes.
When to use it
- Open Gazebo with TurtleBot3 and publish a topic to move the robot.
- List available services and call a service to reset the world in Gazebo.
- List available actions and send an action goal to move TurtleBot3 forward by a set distance.
- Inspect running ROS2 nodes and debug the ROS2 environment via natural language.
Security notes
The companion socket server listens on localhost:8765 and launches local GUI processes (Gazebo, rqt_graph) on instruction from the MCP server. Run it only on a trusted local network; the MCP server can clean up / kill running ROS2 processes and publish to topics, so it has effective control over connected robots and simulators.
ROS MCP FAQ
Which ROS2 distributions are supported?
The project has only been tested with ROS2 Humble Hawksbill. Compatibility with other ROS2 distributions is not guaranteed.
Why are there two servers?
The MCP server (ros-general.py) implements the protocol and maps language to ROS commands, while a separate socket server on localhost:8765 handles GUI operations like launching Gazebo or rqt_graph on the local display.
How do the MCP server and my machine communicate?
Both must be configured with the same ROS_DOMAIN_ID on the same local network to enable ROS node communication.
Alternatives to ROS MCP
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
Code intelligence engine that indexes repos into a persistent knowledge graph for AI coding agents.
Compare ROS MCP with: