ros2-mcp-server

ros2-mcp-server

ros2-mcp-server 是一个基于 Python 的服务，可将模型上下文协议（MCP）与 ROS 2 集成，让 AI 助手通过 ROS 2 话题控制机器人。它通过 FastMCP 处理命令，并以 ROS 2 节点的形式运行，向 /cmd_vel 话题发布 geometry_msgs/Twist 消息以控制机器人移动。

该实现支持“以 0.2 m/s 的速度向前移动 5 秒，然后停止”这类命令，其中 /cmd_vel 发布器名为 pub_cmd_vel。

功能

• MCP 集成：使用 FastMCP 处理来自 MCP 客户端（如 Claude）的命令。
• ROS 2 原生支持：以 ROS 2 节点的形式运行，直接向 /cmd_vel 发布消息。
• 基于时间的控制：支持基于时长的移动命令（例如，移动指定时长后停止）。
• 异步处理：结合 FastMCP 的 asyncio 与 ROS 2 事件循环，实现高效运行。

前置条件

• ROS 2：已安装并加载 Humble 发行版。
• Python：版本为 3.10（与 ROS 2 Humble 兼容所必需）。
• uv：用于依赖管理的 Python 包管理器。
• 依赖项：
  • rclpy：ROS 2 Python 客户端库（随 ROS 2 一起安装）。
  • fastmcp：用于实现 MCP 服务的 FastMCP 框架。
  • numpy：ROS 2 消息类型所需。

安装

1. 克隆仓库：

   git clone https://github.com/kakimochi/ros2-mcp-server.git
   cd ros2-mcp-server
   

2. 配置 Python 版本： 本项目使用 ROS 2 Humble 所需的 Python 3.10。.python-version 文件已完成配置：

   # .python-version content
   3.10
   

3. 项目依赖项： pyproject.toml 文件已配置所需的依赖项：

   # 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. 创建 uv 环境：

   uv venv --python /usr/bin/python3.10
   

5. 激活虚拟环境：

   source .venv/bin/activate
   

   你会看到 (.venv) 出现在命令提示符开头，表示虚拟环境已激活。

6. 安装依赖项：

   uv pip install -e .
   

MCP 服务配置

要将此服务与 Claude 或其他 MCP 客户端搭配使用，需要将其配置为 MCP 服务。设置方法如下：

用于 Claude Desktop

1. 打开 Claude Desktop 设置，并进入 MCP 服务部分。

2. 添加新的 MCP 服务，并使用以下配置：

   "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"
   }
   

   重要：将 /path/to/ros2-mcp-server 替换为仓库的实际路径。例如，如果你将仓库克隆到了 /home/user/projects/ros2-mcp-server，则应使用该路径。

3. 保存配置并重启 Claude。

用于 Cline（VSCode 扩展）

1. 在 VSCode 中，点击侧边栏中的 Cline 图标，打开 Cline 扩展设置。

2. 进入 MCP 服务配置部分。

3. 添加新的 MCP 服务，并使用以下配置：

   "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"
   }
   

   重要：将 /path/to/ros2-mcp-server 替换为仓库的实际路径，与 Claude Desktop 示例相同。

4. 你可以直接在 Cline MCP 设置界面中开启或关闭服务，并立即验证连接，无需重启 VSCode 或重新加载扩展。

使用方法

配置好 MCP 服务后，你可以使用 Claude 向机器人发送命令：

1. 命令示例： 请 Claude 以 0.2 m/s 的速度让机器人向前移动 5 秒：

   Please make the robot move forward at 0.2 m/s for 5 seconds.
   

2. 直接使用工具： 你也可以直接使用 move_robot 工具：

   {
     "linear": [0.2, 0.0, 0.0],
     "angular": [0.0, 0.0, 0.0],
     "duration": 5.0
   }
   

3. 监控 ROS 2 话题： 验证 /cmd_vel 话题的输出：

   ros2 topic echo /cmd_vel
   

测试

1. 使用模拟器：

   • 启动兼容 ROS 2 的模拟器（例如，搭配 TurtleBot3 使用 Gazebo）：

     export TURTLEBOT3_MODEL=burger
     ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
     

   • 使用 Claude 发送移动命令。
   • 观察机器人在 Gazebo 中移动。

2. 使用真实机器人：

   • 确保机器人已正确设置为订阅 /cmd_vel 主题。
   • 使用 Claude 发送移动命令。
   • 机器人应根据命令移动。

3. 预期输出：

   • 服务会记录移动命令和停止命令。
   • Claude 会收到类似 "Successfully moved for 5.0 seconds and stopped" 的响应。

故障排除

• ROS 2 日志记录错误：如果遇到日志目录错误，请确保 ROS_LOG_DIR 环境变量设置为可写目录（例如 /tmp）。
• Python 版本不匹配：请确保使用 Python 3.10，因为 ROS 2 Humble 是针对该版本构建的。
• 连接错误：如果 Claude 报告“Connection closed”错误，请检查 MCP 服务配置是否正确，以及是否已安装所有依赖项。

目录结构

ros2-mcp-server/
├── ros2-mcp-server.py  # Main server script integrating FastMCP and ROS 2
├── pyproject.toml      # Project dependencies and metadata
├── .python-version     # Python version specification
├── .gitignore          # Git ignore file
└── README.md           # This file

限制

• 单个主题：目前支持使用 Twist 消息的 /cmd_vel。如需支持其他主题或服务，请扩展 ros2-mcp-server.py。
• 基本命令：目前支持简单的移动命令。更复杂的行为需要额外实现。

许可证

MIT License

Copyright (c) 2025 kakimochi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

请注意，本项目使用了 FastMCP，其采用 Apache License 2.0 许可。该许可证的条款也适用于 FastMCP 组件的使用。

致谢

• 使用 FastMCP 和 ROS 2 构建。