ros2-mcp-server

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

此实现支持诸如“以 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. 克隆仓库：
   bash
   git clone https://github.com/kakimochi/ros2-mcp-server.git
   cd ros2-mcp-server

2. Python 版本配置：
   该项目使用 Python 3.10，这是 ROS 2 Humble 所需的版本。.python-version 文件已经配置好：
   bash

   .python-version 内容

   3.10

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

   pyproject.toml 内容

   [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 环境：
   bash
   uv venv --python /usr/bin/python3.10

5. 激活虚拟环境：
   bash
   source .venv/bin/activate

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

6. 安装依赖项：
   bash
   uv pip install -e .

MCP 服务器配置

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

对于 Claude Desktop

1. 打开 Claude Desktop 设置并导航到 MCP 服务器部分。

2. 添加一个新的 MCP 服务器，配置如下：
   json
   "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 服务器，配置如下：
   json
   "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 秒：

   请让机器人以 0.2 m/s 的速度前进 5 秒。

2. 直接使用工具：
   您也可以直接使用 move_robot 工具：
   json
   {
   "linear": [0.2, 0.0, 0.0],
   "angular": [0.0, 0.0, 0.0],
   "duration": 5.0
   }

3. 监控 ROS 2 主题：
   验证 /cmd_vel 主题输出：
   bash
   ros2 topic echo /cmd_vel

测试

1. 使用模拟器：

   • 启动一个与 ROS 2 兼容的模拟器（例如，带有 TurtleBot3 的 Gazebo）：
     bash
     export TURTLEBOT3_MODEL=burger
     ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py

   • 使用 Claude 发送移动命令。

   • 观察 Gazebo 中机器人的移动情况。

2. 使用真实机器人：

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

3. 预期输出：

   • 服务器记录移动命令和停止命令。
   • Claude 接收到类似以下响应："成功移动了 5.0 秒并停止"。

故障排除

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

目录结构

ros2-mcp-server/
├── ros2-mcp-server.py # 集成 FastMCP 和 ROS 2 的主服务器脚本
├── pyproject.toml # 项目依赖和元数据
├── .python-version # Python 版本说明
├── .gitignore # Git 忽略文件
└── README.md # 本文档

限制

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

许可证

MIT 许可证

版权所有 (c) 2025 kakimochi

特此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的权利，不受限制地处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向其提供软件的人这样做，但须遵守以下条件：

上述版权声明和此许可声明必须包含在软件的所有副本或重要部分中。

本软件按“原样”提供，不附带任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人都不对因使用本软件或无法使用本软件而导致的任何索赔、损害或其他责任负责，无论是合同诉讼、侵权行为还是其他原因引起的。

请注意，此项目使用了 FastMCP，它基于 Apache License 2.0 许可。FastMCP 组件的使用也受该许可证条款的约束。

致谢- 构建于 FastMCP 和 ROS 2。