ROS2 MCP Server

ros2-mcp-服务器

ros2-mcp-server是一个基于 Python 的服务器，它将模型上下文协议 (MCP) 与 ROS 2 集成，使 AI 助手能够通过 ROS 2 主题控制机器人。它通过 FastMCP 处理命令，并作为 ROS 2 节点运行，将geometry_msgs/Twist消息发布到/cmd_vel主题来控制机器人的运动。

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

特征

• MCP 集成：使用 FastMCP 处理来自 MCP 客户端（例如 Claude）的命令。
• ROS 2 Native ：作为 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 .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 venv --python /usr/bin/python3.10
5. 激活虚拟环境：
   source .venv/bin/activate
   您将看到(.venv)出现在命令提示符的开头，表明虚拟环境处于活动状态。
6. 安装依赖项：
   uv pip install -e .

MCP 服务器配置

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

对于克劳德桌面

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 米/秒的速度向前移动机器人 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
   • 使用克劳德发送移动命令。
   • 观察机器人在 Gazebo 中的移动。
2. 使用真实机器人：
   • 确保您的机器人已正确设置以订阅/cmd_vel主题。
   • 使用克劳德发送移动命令。
   • 机器人应该按照命令移动。
3. 预期输出：
   • 服务器记录移动命令和停止命令。
   • 克劳德收到了这样的回应： "Successfully moved for 5.0 seconds and stopped" 。

故障排除

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

目录结构

限制

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

执照

请注意，本项目使用FastMCP ，该协议遵循 Apache 2.0 许可证。该许可证的条款也适用于 FastMCP 组件的使用。

致谢

• 使用FastMCP和ROS 2构建。