ROS2 MCP Server

ros2-mcp-server

ros2-mcp-server is a Python-based server that integrates the Model Context Protocol (MCP) with ROS 2, enabling AI assistants to control robots via ROS 2 topics. It processes commands through FastMCP and runs as a ROS 2 node, publishing geometry_msgs/Twist messages to the /cmd_vel topic to control robot movement.

This implementation supports commands like "move forward at 0.2 m/s for 5 seconds and stop," with the /cmd_vel publisher named pub_cmd_vel.

Features

• MCP Integration: Uses FastMCP to handle commands from MCP clients (e.g., Claude).
• ROS 2 Native: Operates as a ROS 2 node, directly publishing to /cmd_vel.
• Time-Based Control: Supports duration-based movement commands (e.g., move for a specified time and stop).
• Asynchronous Processing: Combines FastMCP's asyncio with ROS 2's event loop for efficient operation.

Prerequisites

• ROS 2: Humble distribution installed and sourced.
• Python: Version 3.10 (required for compatibility with ROS 2 Humble).
• uv: Python package manager for dependency management.
• Dependencies:
  • rclpy: ROS 2 Python client library (installed with ROS 2).
  • fastmcp: FastMCP framework for MCP server implementation.
  • numpy: Required by ROS 2 message types.

Installation

1. Clone the Repository:
   git clone https://github.com/kakimochi/ros2-mcp-server.git cd ros2-mcp-server
2. Python Version Configuration: This project uses Python 3.10 as required by ROS 2 Humble. The .python-version file is already configured:
   # .python-version content 3.10
3. Project Dependencies: The pyproject.toml file is configured with the necessary dependencies:
   # pyproject.toml content [project] name = "ros2-mcp-server" version = "0.1.0" description = "ROS 2 MCP Server" readme = "README.md" requires-python = ">=3.10" dependencies = [ "fastmcp", "numpy", ]
4. Create uv Environment:
   uv venv --python /usr/bin/python3.10
5. Activate the Virtual Environment:
   source .venv/bin/activate
   You'll see (.venv) appear at the beginning of your command prompt, indicating that the virtual environment is active.
6. Install Dependencies:
   uv pip install -e .

MCP Server Configuration

To use this server with Claude or other MCP clients, you need to configure it as an MCP server. Here's how to set it up:

For Claude Desktop

1. Open Claude Desktop settings and navigate to the MCP servers section.
2. Add a new MCP server with the following configuration:
   "ros2-mcp-server": { "autoApprove": [], "disabled": false, "timeout": 60, "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" ], "transportType": "stdio" }
   Important: Replace /path/to/ros2-mcp-server with the actual path to your repository. For example, if you cloned the repository to /home/user/projects/ros2-mcp-server, you would use that path instead.
3. Save the configuration and restart Claude.

For Cline (VSCode Extension)

1. In VSCode, open the Cline extension settings by clicking on the Cline icon in the sidebar.
2. Navigate to the MCP servers configuration section.
3. Add a new MCP server with the following configuration:
   "ros2-mcp-server": { "autoApprove": [], "disabled": false, "timeout": 60, "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" ], "transportType": "stdio" }
   Important: Replace /path/to/ros2-mcp-server with the actual path to your repository, as in the Claude Desktop example.
4. You can immediately toggle the server on/off and verify the connection directly from the Cline MCP settings interface without needing to restart VSCode or reload the extension.

Usage

Once the MCP server is configured, you can use Claude to send commands to the robot:

1. Example Command: Ask Claude to move the robot forward at 0.2 m/s for 5 seconds:
   Please make the robot move forward at 0.2 m/s for 5 seconds.
2. Direct Tool Usage: You can also use the move_robot tool directly:
   { "linear": [0.2, 0.0, 0.0], "angular": [0.0, 0.0, 0.0], "duration": 5.0 }
3. Monitor ROS 2 Topics: Verify the /cmd_vel topic output:
   ros2 topic echo /cmd_vel

Testing

1. With a Simulator:
   • Launch a ROS 2-compatible simulator (e.g., Gazebo with TurtleBot3):
     export TURTLEBOT3_MODEL=burger ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
   • Use Claude to send movement commands.
   • Observe the robot moving in Gazebo.
2. With a Real Robot:
   • Ensure your robot is properly set up to subscribe to the /cmd_vel topic.
   • Use Claude to send movement commands.
   • The robot should move according to the commands.
3. Expected Output:
   • The server logs movement commands and stop commands.
   • Claude receives a response like: "Successfully moved for 5.0 seconds and stopped".

Troubleshooting

• ROS 2 Logging Errors: If you encounter logging directory errors, ensure the ROS_LOG_DIR environment variable is set to a writable directory (e.g., /tmp).
• Python Version Mismatch: Ensure you're using Python 3.10, as ROS 2 Humble is built for this version.
• Connection Errors: If Claude reports "Connection closed" errors, check that the MCP server configuration is correct and that all dependencies are installed.

Directory Structure

Limitations

• Single Topic: Currently supports /cmd_vel with Twist messages. Extend ros2-mcp-server.py for other topics or services.
• Basic Commands: Currently supports simple movement commands. More complex behaviors would require additional implementation.

License

Note that this project uses FastMCP, which is licensed under the Apache License 2.0. The terms of that license also apply to the use of FastMCP components.

Acknowledgments

• Built with FastMCP and ROS 2.