The ROS MCP Server translates natural language commands into ROS commands, enabling flexible, cloud- or desktop-based control of robots through a WebSocket bridge that works with both ROS and ROS2. It lets you connect AI systems or LLMs to robot action while interacting with existing ROS topics and services without modifying your robot’s core code.

How to use

Set up an MCP client (your AI system or language model) to communicate with the ROS MCP Server over WebSocket. You can guide the robot with natural language prompts like “Make the robot move forward” and the MCP will translate your request into ROS commands for the robot to execute. The server interacts with both ROS and ROS2 ecosystems, so you can work with the version your robot uses, without rewriting your ROS tooling.

To integrate, ensure your MCP client supports sending commands to the ros-mcp-server over its WebSocket interface. The server accepts natural language inputs via MCP functions, and translates them into suitable geometry_msgs/Twist, sensor_msgs/Image, or sensor_msgs/JointState outputs for ROS topics and services.

How to install

Prerequisites you need before installing the ROS MCP Server: a working Node.js runtime (for Smithery) or Python environment (for local runtime), and access to a ROS or ROS2 system with rosbridge available.

Install via Smithery to get the client-ready package quickly. Run this command in your terminal to install the ROS MCP Server for Claude Desktop automatically:

npx -y @smithery/cli install @lpigeon/ros-mcp-server --client claude

If you prefer a local setup, install uv and prepare a dedicated Python environment to run the MCP server process. Follow these steps to set up uv and the server locally.

curl -LsSf https://astral.sh/uv/install.sh | sh

or

pip install uv

Create and activate a Python virtual environment (optional but recommended), then install dependencies and set up the MCP server configuration.

uv venv source .venv/bin/activate

Configure the MCP server to point to your local ros-mcp-server code base. Create or edit mcp.json with the server configuration that points to the runtime entry script.

{ "mcpServers": { "ros-mcp-server": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcp-server", "run", "server.py" ] } } }

## Additional configuration and runtime notes

Before you start, set up rosbridge to bridge ROS/ROS2 topics to the MCP server. You can connect using either ROS 1 or ROS 2 tooling.

Choose one of the two rosbridge deployment options depending on your ROS version.

ROS 1 start command example (rosbridge WebSocket):

roslaunch rosbridge_server rosbridge_websocket.launch

ROS 2 start command example (rosbridge WebSocket):

ros2 launch rosbridge_server rosbridge_websocket_launch.xml

With rosbridge running, your MCP client can send natural language prompts to the ROS MCP Server, which will translate them into actions and publish to the appropriate ROS topics or call the needed services.

## Troubleshooting and tips

If you encounter connection issues, verify that rosbridge is reachable at the configured WebSocket URL and that the MCP server’s LOCAL\_IP and ROSBRIDGE\_IP/PORT are correctly set in server.py.

Check the status of rosbridge\_server and ros topic to confirm messages are being exchanged as expected.

For development, you can extend the MCP tool interface to add new robot control or sensor functions as your hardware or tasks evolve.

## Implementation details and examples

The ROS MCP Server supports a practical set of ROS message types and integrates cleanly with LLM-based controllers through MCP functions. It is designed to operate with both ROS and ROS2, minimizing the need to modify your robot’s existing codebase while enabling flexible, AI-driven control.