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 m/s的速度前进5秒并停止”等命令 /cmd_vel 出版商名称 pub_cmd_vel.

特性

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

先决条件

• ROS 2：安装和采购的分销渠道简陋。
• python：版本3.10（与ROS 2 Humble兼容所需）。
• 紫外线：用于依赖管理的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

1. Python版本配置:

本项目按照ROS 2 Humble的要求使用Python 3.10。这 .python-version 文件已配置：

   # .python-version content
   3.10

1. 项目依赖项:

这 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",
   ]

1. 创建紫外线环境:

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

1. 激活虚拟环境:

   source .venv/bin/activate

你会看到的 (.venv) 出现在命令提示符的开头，表示虚拟环境处于活动状态。

1. 再进行:

   uv pip install -e .

MCP服务器配置

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

适用于克劳德桌面

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

1. 添加具有以下配置的新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，你会选择那条路。

1. 保存配置并重新启动Claude。

对于Cline（VSCode扩展）

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

1. 导航到MCP服务器配置部分。

1. 添加具有以下配置的新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示例中所示。

1. 您可以立即打开/关闭服务器，并直接从Cline MCP设置界面验证连接，而无需重新启动VSCode或重新加载扩展。

用法

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

1. 命令示例:

让克劳德以0.2 m/s的速度向前移动机器人5秒：

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

1. 直接工具使用:

您还可以使用 move_robot 工具直接：

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

1. 监控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中的移动。

1. 与一个真正的机器人:

- 确保您的机器人已正确设置以订阅 /cmd_vel 主题。 - 使用Claude发送移动命令。 - 机器人应该按照命令移动。

1. 期望输出:

- 服务器记录移动命令和停止命令。 - Claude收到的回复如下： "Successfully moved for 5.0 seconds and stopped".

故障排除

• ROS 2日志错误：如果遇到日志目录错误，请确保 ROS_LOG_DIR 环境变量被设置为可写目录（例如。， /tmp).
• Python版本不匹配：确保您使用的是Python 3.10，因为ROS 2 Humble是为此版本构建的。
• 连接错误：如果Claude报告“连接关闭”错误，请检查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

局限性

• 单一主题：目前支持 /cmd_vel 随着 Twist 信息。扩展 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许可证2.0获得许可。该许可证的条款也适用于FastMCP组件的使用。

致谢