ros2-mcp-server

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原生：作为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内容
   3.10
   

3. 项目依赖项： pyproject.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环境：

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

5. 激活虚拟环境：

   source .venv/bin/activate
   

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

6. 安装依赖项：

   uv pip install -e .
   

MCP服务器配置

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

对于Claude桌面

1. 打开Claude桌面设置，导航至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桌面示例一样。

4. 您可以直接在Cline MCP设置界面切换服务器开关并验证连接，无需重新启动VSCode或重新加载扩展。

使用

一旦MCP服务器配置完成，您可以使用Claude发送命令给机器人：

1. 示例命令： 要求Claude让机器人以0.2米/秒的速度前进5秒：

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

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收到类似这样的响应：“成功移动了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构建。