Integrates MCP with ROS 2 to control robots via the /cmd_vel topic using Twist messages.
Configuration
View docs{
"mcpServers": {
"kakimochi-ros2-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/ros2-mcp-server",
"run",
"bash",
"-c",
"export ROS_LOG_DIR=/tmp && source /opt/ros/humble/setup.bash && python3 /path/to/ros2-mcp-server/ros2-mcp-server.py"
],
"env": {
"ROS_LOG_DIR": "/tmp"
}
}
}
}You run a ROS 2 MCP server that accepts movement commands from MCP clients and translates them into ROS 2 Twist messages published on the /cmd_vel topic. This lets AI assistants control a robot’s motion through standard MCP workflows while leveraging ROS 2 natively for robot control.
Connect an MCP client to the ROS 2 MCP server to issue movement commands. You can request moving forward, turning, or other velocity-based actions for a specified duration. The server translates those commands into geometry_msgs/Twist messages and publishes them to the /cmd_vel topic, which your robot subscribes to for real-time motion control. Use a client that supports MCP style commands to send a move instruction like a forward move at a given speed for a given time, and observe the robot respond accordingly. You can also use the off-the-shelf move_robot tool to send a structured movement request that includes linear and angular components and a duration.
# Prerequisites
# 1) Ensure ROS 2 Humble is installed and sourced
# 2) Install Python 3.10
# 3) Install uv (Python environment manager) and dependencies
# Clone the project
git clone https://github.com/kakimochi/ros2-mcp-server.git
cd ros2-mcp-server
# Python version configuration
# .python-version is preset to 3.10
# Create uv environment
uv venv --python /usr/bin/python3.10
# Activate the virtual environment
source .venv/bin/activate
# Install dependencies
uv pip install -e .To run the MCP server locally, you start a stdio-based MCP server that uses uv to spawn a Python script. The server runs in a directory you specify and launches a ROS 2 aware process that publishes to /cmd_vel. The typical runtime command includes exporting logging to a temporary directory, sourcing the ROS Humble setup script, and starting the Python MCP server script.
- With a simulator: Launch a ROS 2 compatible simulator (for example, Gazebo with TurtleBot). Then send a movement command from the MCP client and verify the robot moves accordingly in the simulation. - With a real robot: Ensure the robot is subscribed to /cmd_vel, then issue commands from the MCP client and observe the robot’s motion. - Monitor topic output to verify correct command publishing: ros2 topic echo /cmd_vel.
If you encounter ROS 2 logging directory errors, set ROS_LOG_DIR to a writable directory such as /tmp. Ensure you are using Python 3.10 for compatibility with ROS 2 Humble. If the MCP client reports connection issues, double-check the MCP server configuration and that all dependencies are installed correctly.
The server supports time-based movement commands, where the robot moves for a specified duration and then stops. For a direct tool-based command, you can use the move_robot tool with a structure that includes linear and angular components and a duration. Example usage reads as moving forward at 0.2 m/s for 5 seconds and then stopping, which results in a corresponding /cmd_vel Twist message sequence.
move_robot - Sends a structured movement request with specified linear and angular velocities and a duration. The server translates this into Velocity commands on /cmd_vel and stops after the duration.
Limit MCP client access to trusted agents in your network. Use transport settings and authentication as supported by your MCP client implementation to avoid unauthorized motor commands.
Tool to command a robot to move with specified linear and angular velocities for a given duration, publishing Twist messages to /cmd_vel.