ros

The ROS MCP Server bridges large language models (LLMs) with your ROS1 or ROS2 robotics environment, enabling natural language control and observation of robot state. It exposes ROS topics, services, parameters, and message types to the LLM, allowing the model to subscribe to topics, publish commands, call services, and read sensor data in real time. This two-way integration enables you to issue natural language instructions (for example, ‘move arm to pose x,y,z’ or ‘check shoulder temperature’), while the LLM receives rich feedback from the robot’s ROS ecosystem, including topic streams and service responses. The server is designed to work with both ROS1 and ROS2, and it can be integrated with any MCP-enabled LLM (Claude, Gemini, ChatGPT, etc.).

To use it, run the MCP server with the ROS backend enabled. Connect your MCP-enabled LLM client to the server and begin issuing natural-language commands. You can then instruct the robot, request live sensor data, inspect available topics/services, and query or modify parameters, all while the LLM remains aware of the robot’s state within ROS.

Prerequisites:

• Python 3.10 or newer
• pip (version 23.0 or newer)
• A ROS1 or ROS2 environment configured and running (roscore for ROS1 or ros2 daemon for ROS2)

Install the ROS MCP Server from PyPI (adjust package name if your distribution differs):

python -m pip install ros-mcp-server

Verify installation:

python -m ros_mcp_server --version

Run the server (example):

python -m ros_mcp_server

Configuration:

• Ensure ROS environment is sourced in the same shell where you run the server.
• Adjust any required environment variables or ROS_DOMAIN_ID as needed for your network and ROS configuration.

If you prefer building from source, follow the repository's installation-from-source instructions in docs/installation-from-source.md and ensure you have all ROS dependencies installed.

Tips and common issues:

• Ensure your ROS workspace is sourced before starting the MCP server so ROS01/ROS2 nodes are visible to the MCP backend.
• If topics or services aren’t appearing, confirm that your ROS environment is properly configured and that the robot’s ROS nodes are running.
• For ROS2, verify the DDS/RTPS network settings to avoid discovery issues on multi-machine setups.
• When deploying with an MCP-enabled LLM, consider enabling permission controls to restrict which topics/services the model can access.
• Check the server logs for ROS topic/service discovery messages and for any ROS-specific errors that might indicate misconfigurations.
• If you need to run the server in a container or dev container, ensure the container has access to the host’s ROS runtime (e.g., by sharing the ROS workspace and proper networking).