ros

This MCP server enables natural language commands to control a ROS 2 environment. The ros-general.py MCP maps user input to ROS topic publications, service calls, and action goals, allowing you to observe and manipulate ROS behavior via a web-based or CLI interface. It communicates with a lightweight socket server (socket_server.py) on localhost:8765 to manage GUI-related tools such as Gazebo or rqt_graph, and to coordinate actions on the local machine. To use it, ensure your ROS 2 workspace is running and that both the MCP server and the local machine share the same ROS_DOMAIN_ID on the same network. The system supports Topic Management, Node Control, Service Interaction, Action Support, GUI Integration, Environment Debugging, and Process Management for ROS 2—giving you a consolidated command surface for robot control and experimentation.

Once running, you can prompt the MCP with requests like: list ROS topics and publish a message, enumerate nodes, call a service such as resetting the simulation world, or send a goal to an action like moving a robot a certain distance. The available tools and their capabilities are documented in the project wiki, referenced in the README, and exposed through the MCP’s natural language interface.

Prerequisites

• A ROS 2 Humble Hawksbill installation and a compatible Python environment
• Python 3.10+
• uv package manager (install as shown below)
• websockets >= 15.0.1
• Claude Desktop (optional, for Claude integration)

Installation steps

1. Clone the repository and navigate to it

git clone https://github.com/Yutarop/ros-mcp.git
cd ros-mcp

2. Create and activate a Python virtual environment, then install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install "websockets>=15.0.1"
pip install -e .

3. Install and configure uv (if not already installed)

# If uv is not installed globally, install via your preferred method
# Example via pipx (optional):
pipx install uv

4. Run the MCP server (ros-general)

uv run ros-general.py

5. Run the socket server (optional for GUI integration)

python3 socket_server.py

Notes

• Ensure your ROS_DOMAIN_ID is consistently set across devices to enable node communication between the MCP server and the local machine.
• If you modify paths or the script locations, update the environment or the command line accordingly as shown in the README examples.

Environment and configuration tips:

• ROS_DOMAIN_ID must be set on both the MCP host and the client machine. You can export it in your shell or within the uv command wrapper as shown in the README example.
• The MCP relies on the local ROS 2 environment being sourced before executing commands (e.g., source /opt/ros/humble/setup.bash). Ensure your environment setup is compatible with your ROS installation.
• If you encounter permission or path issues, verify absolute paths in your environment and make sure the ros-general.py script is accessible by the user running the MCP.
• The socket server is a lightweight GUI bridge. Start it separately if you intend to use Gazebo or rqt_graph via the MCP’s GUI integration.
• Refer to the wiki for a complete list of available tools and how to use each feature (Topic Management, Node Control, Service Interaction, Action Support, GUI Integration, Environment Debugging, Process Management).