ROS MCP
Provides tools for controlling robots in ROS 2 environments, including listing and publishing topics, calling services, sending action goals, and launching ROS GUI tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ROS MCP list available topics and publish to /cmd_vel to move the robot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ROS MCP
ROS MCP is a MCP server designed for controlling robots in ROS environments using natural language. It supports communication via ROS topics, services, and actions, and works with any ROS message type.
Related MCP server: ROS2 MCP Server
Demo
Test to see if ros topics, services, and actions can be used.
https://github.com/user-attachments/assets/61143c37-fb73-4998-9cbc-844d92ae61d9
Prompt used (Topic)
Open gazebo with TurtleBot3 and publish topic to move it.
Prompt used (Service)
Show me service list and call service to reset the world in Gazebo.
Prompt used (Action)
Show me action list and call action to move the TurtleBot3 forward for 1m.
Components
Socket Server (
socket_server.py): A lightweight server that runs on localhost:8765 to handle GUI-related operations. It receives instructions from the MCP server to launch tools such asGazeboorrqt_graphon the local display.MCP Server (
ros-general.py): A Python-based server that implements the MCP. It processes natural language input, maps it to ROS commands, and communicates with the socket server. To enable node communication between the MCP server and the local machine, both must be configured with the sameROS_DOMAIN_IDon the same local network.
Overview of MCP Tools
Topic Management: List, monitor, and publish to ROS2 topicsNode Control: List and inspect running ROS2 nodesService Interaction: Call ROS2 services with customAction Support: Send goals to ROS2 actionsGUI Integration: Launch ROS2 GUI tools via WebSocket serverEnvironment Debugging: Check ROS2 setup and configurationProcess Management: Clean up running ROS2 processes
Please refer here for more details.
Getting Started
Requirements
ROS2 Humble Hawksbill (This project has only been tested with ROS2 Humble. Compatibility with other ROS2 distributions is not guaranteed.)
Python 3.10+
websockets >= 15.0.1
uv package manager (Installing uv)
Other dependencies as listed in
pyproject.toml
Installation
Git clone and install websockets package
git clone git@github.com:Yutarop/ros-mcp.git
cd ros-mcp
pip install "websockets>=15.0.1"Activate .venv and install dependencies
uv venv
source .venv/bin/activate
uv pip install -e .Claude Settings (claude_desktop_config.json)
To use the MCP server correctly with Claude Desktop, you need to modify the claude_desktop_config.json file with appropriate values.
{
"mcpServers": {
"ros-general": {
"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"
]
}
}
}💡 Replace the following placeholders:
/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcpReplace with the absolute path the ros-mcp directory. For example: /home/ubuntu/ros-mcpYOUR_ROS_DOMAIN_IDReplace 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:echo $ROS_DOMAIN_IDIf nothing is printed, the domain ID is not set, and the default value 0 will be used. Alternatively, you can set it manually using the following command:
export ROS_DOMAIN_ID=10 # Replace 10 with your desired domain ID/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-general.pyReplace with the absolute path to your ros-general.py script. For example: /home/ubuntu/ros-mcp/ros-general.py
Running the Servers
Start MCP server
Make sure your virtual environment is activated before running the MCP server:
(ros-mcp) $ uv run ros-general.pyStart socket server
python3 socket_server.py💡not in the virtual environment!
Available Tools
24 toolscall_ros2_serviceA
Calls a ROS 2 service with the specified name, type, and optional request.
Args:
service_name: Name of the service to call.
srv_type: Type of the service (e.g., "std_srvs/srv/Empty").
request: Request payload in string format (e.g., "{r: 255, g: 0, b: 0, width: 2, off: 0}").
If the service type does not require a request (e.g., std_srvs/srv/Empty),
this can be omitted or set to None.
Example:
Call a service without a request:
service_name = "/clear"
srv_type = "std_srvs/srv/Empty"
Call a service with a request:
service_name = "/turtle1/set_pen"
srv_type = "turtlesim/srv/SetPen"
request = "{r: 255, g: 0, b: 0, width: 2, off: 0}"
Inputs: srv_type (required), service_name (required), request.
check_ros2_topic_hzB
Displays the publishing frequency (Hz) of a given ROS 2 topic.
Args:
topic_name: Name of the topic (e.g., /scan)
Example: "Check the message rate on /scan" → ros2 topic hz /scan
Inputs: topic_name (required).
check_topic_statusA
Checks whether a specific ROS2 topic is actively publishing messages.
Args:
topic_name: The name of the ROS2 topic to check
Example: Used when the user asks "Is the topic /scan publishing data?"
Inputs: topic_name (required).
clean_all_ros2_nodesA
Kills all currently running ROS 2 and Gazebo related processes to clean the environment.
Inputs: no named parameters.
debug_ros2_environmentB
Debug ROS 2 environment variables and setup.
Inputs: no named parameters.
echo_ros2_topicB
Echo messages from a ROS2 topic for a specified number of messages.
Args:
topic_name: Name of the topic to echo
count: Number of messages to capture (default: 1)
Example: Echo 5 messages from /scan topic
Inputs: topic_name (required), count.
find_ros2_packageA
Searches for available ROS 2 packages that match a given keyword.
Args:
pkg_name: Partial or full name of the package to search for
Example: "Are there any packages related to turtle?" → ros2 pkg list | grep turtle
Inputs: pkg_name (required).
get_ros2_node_infoC
Shows detailed information about a specific ROS 2 node.
Args:
node_name: Name of the node (e.g., /turtlesim)
Example: "Tell me about node /turtlesim" → ros2 node info /turtlesim
Inputs: node_name (required).
get_topic_infoB
Get detailed information about a specific ROS2 topic.
Args:
topic_name: Name of the topic to get info about
Example: Get information about /cmd_vel topic
Inputs: topic_name (required).
launch_gazeboA
Launch Gazebo simulation environment via WebSocket server.
Example: Launch Gazebo for physics simulation
Inputs: no named parameters.
launch_rqt_graphA
Launch rqt_graph GUI tool via WebSocket server.
Example: Launch rqt_graph to visualize ROS2 node connections
Inputs: no named parameters.
launch_rvizB
Launch RViz2 GUI tool via WebSocket server.
Example: Launch RViz2 for visualization
Inputs: no named parameters.
launch_turtlebot3_empty_worldB
Launch TurtleBot3 in empty world in Gazebo via WebSocket server.
Example: Launch TurtleBot3 in an empty world for simulation
Inputs: no named parameters.
launch_turtlebot3_worldB
Launch TurtleBot3 world in Gazebo via WebSocket server.
Example: Launch TurtleBot3 in a world environment for simulation
Inputs: no named parameters.
launch_turtlesimA
Launch turtlesim GUI application via WebSocket server.
Example: Launch turtlesim for turtle simulation
Inputs: no named parameters.
list_ros2_actionsA
Lists available ROS 2 actions.
Example: No arguments needed. Just returns the list.
Inputs: no named parameters.
list_ros2_nodesA
Lists currently running ROS 2 nodes.
Example: "Which nodes are currently running?" → ros2 node list
Inputs: no named parameters.
list_ros2_servicesA
Lists available ROS 2 services.
Example: No arguments needed. Just returns the list.
Inputs: no named parameters.
list_topicsA
Displays a list of currently accessible ROS2 topics.
Example: Used when the user asks "What topics are available?"
Inputs: no named parameters.
publish_ros2_topicA
Publishes a message to a specific ROS 2 topic for a given duration (in seconds).
Args:
topic: Topic name to publish to (e.g., "/cmd_vel")
msg_type: ROS 2 message type (e.g., "geometry_msgs/msg/Twist")
msg_content: Message to send (e.g., '{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.5}}')
duration: Duration in seconds to continue publishing
Example:
topic: "/cmd_vel"
msg_type: "geometry_msgs/msg/Twist"
msg_content: '{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.5}}'
duration: 5
Inputs: topic (required), duration (required), msg_type (required), msg_content (required).
run_ros2_doctorA
Runs ros2 doctor to check ROS 2 environment setup and issues.
Example: No arguments needed. Just runs the doctor tool.
Inputs: no named parameters.
run_ros2_executableB
Runs a ROS 2 executable from a specified package.
Args:
package: Name of the ROS2 package
executable: Name of the executable to run
Example: "Start the turtlesim node" → ros2 run turtlesim turtlesim_node
Inputs: package (required), executable (required).
send_ros2_action_goalB
Sends a goal to a ROS 2 action.
Args:
action_name: Name of the action
action_type: Action type (e.g., example_interfaces/action/Fibonacci)
goal: Goal message (e.g., "{order: 5}")
Example:
action_name: "/fibonacci"
action_type: "example_interfaces/action/Fibonacci"
goal: "{order: 5}"
Inputs: goal (required), action_name (required), action_type (required).
show_ros2_interfaceB
Shows the interface (definition) for a given ROS 2 message or service type.
Args:
msg_type: The interface type to show (e.g., std_msgs/msg/String)
Example: msg_type: "std_msgs/msg/String"
Inputs: msg_type (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct ROS 2 operation (e.g., call service, echo topic, launch simulation, list nodes). Despite some similar verbs like 'check' and 'get', the descriptions clearly differentiate the tools, leaving no ambiguity.
Tool names consistently use verb_noun pattern, but there is minor inconsistency in whether 'ros2' is included in the noun (e.g., 'list_topics' vs 'list_ros2_services'). This slight deviation from perfect uniformity justifies a 4.
With 24 tools, the set is comprehensive but slightly above the typical 3-15 range for well-scoped servers. However, each tool serves a clear purpose in the ROS 2 ecosystem, so it is not excessive.
The tool set covers major ROS 2 interactions: listing, publishing, service calls, actions, node info, and launching simulations. Minor gaps like a specific stop-node tool are absent, but agents can work around using 'clean_all_ros2_nodes' or other means.
Related MCP Connectors
Zero-auth ROS 2 Humanoid, Q3 Proxemics, 3-Level Voice Arbiter, A2A-MCP Bridge & W3C VC 2.0.
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables control of ROS/ROS2 robots through natural language commands by translating LLM instructions into ROS topics and services. Supports cross-platform WebSocket-based communication with existing robot systems without requiring code modifications.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI tools to interact with ROS2 robotics systems through natural language commands. Supports topic publishing/subscribing, service calls, message analysis, and auto-discovery of ROS2 interfaces for debugging and controlling robots.Mozilla Public 2.0
- AlicenseNot gradedqualityCmaintenanceEnables natural language command control of robots via ROS2, with a web portal for real-time visualization and interaction.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.Apache 2.0