ROS-MCP-Server: LLM与ROS系统的MCP桥梁
ROS-MCP-Server 是一个开源项目，实现了大语言模型与机器人操作系统之间的双向集成。它通过 MCP 协议与 LLM 端通信，通过 rosbridge WebSocket 协议连接 ROS 系统，充当协议翻译层。
项目地址：https://github.com/robotmcp/ros-mcp-server | Stars: 1291 | 许可证: Apache 2.0 | 主页：https://robotmcp.ai
核心能力
- 自然语言控制机器人 - 将对话式命令转换为 ROS topics、services 和 parameters
- 实时机器人观测 - 流式传输传感器数据、监控机器人状态、检查 ROS 生态系统
- 零机器人代码修改 - 通过 rosbridge 接口集成现有 ROS 系统，无需修改机器人代码
- 多平台支持 - 兼容 ROS1 (Noetic) 和 ROS2 (Jazzy、Humble 等) 及多种机器人平台
- 通用 MCP 客户端兼容 - 支持 Claude Code、Claude Desktop、Codex CLI、Gemini CLI、ChatGPT、Cursor 等
系统架构
ROS-MCP-Server 采用三层架构设计：
- LLM 通信层 - 通过 MCP 协议与 LLM 客户端通信，接收工具调用请求并返回结果
- 协议转换层 - 将 MCP 工具调用转换为 rosbridge WebSocket JSON 消息
- ROS 集成层 - 通过 rosbridge 与 ROS/ROS2 系统交互，操作 topics、services、parameters
工具分类
服务器注册了以下工具类别：
| 类别 | 工具函数 | 功能说明 |
|---|---|---|
| Topic 工具 | list_topics()、get_topic_type()、subscribe_to_topic()、publish_once() | 发现和操作 ROS 主题 |
| Service 工具 | list_services()、get_service_type()、call_service() | 枚举和调用 ROS 服务 |
| Parameter 工具 | get_param()、set_param()、list_params() | 读写 ROS 参数服务器 |
| System 工具 | connect_to_robot()、test_connectivity() | 连接管理和网络检测 |
| Action 工具 | Action 相关工具函数 | ROS action 支持 |
| Node 工具 | 节点相关工具函数 | 列出和检查运行中的节点 |
| Image 工具 | 图像相关工具函数 | 捕获和分析摄像头画面 |
| Robot Config 工具 | 配置相关工具函数 | 获取机器人规格信息 |
核心组件
| 组件 | 文件 | 功能 |
|---|---|---|
| FastMCP 服务器 | server.py / ros_mcp/main.py | 主 MCP 服务器进程，工具注册和 LLM 通信，支持 stdio/http/streamable-http 传输 |
| WebSocket 管理器 | utils/websocket_manager.py | 管理 rosbridge WebSocket 连接和消息序列化 |
| 网络工具 | utils/network_utils.py | 连通性测试，提供 ping_ip_and_port() 函数 |
| 工具注册 | ros_mcp/tools/__init__.py | 按类别注册所有 ROS MCP 工具 |
| 图像处理 | utils/websocket.py | 解析 ROS 图像消息（支持 CompressedImage 和原始图像格式） |
安装指南
步骤一: 配置 AI 客户端
使用 uv 包管理器快速配置 Claude Code：
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 添加 MCP 服务器到 Claude Code
claude mcp add ros-mcp -- uvx ros-mcp --transport=stdio支持的其他客户端包括：
| 客户端 | 说明 |
|---|---|
| Codex CLI | OpenAI 的 CLI 代理 |
| Gemini CLI | Google 的 CLI |
| Claude Desktop | Anthropic 桌面应用 |
| ChatGPT | OpenAI 桌面应用 |
| Cursor | AI 增强 IDE |
步骤二: 启动 Rosbridge
在机器人端安装并启动 rosbridge_server：
# 安装 rosbridge（以 ROS2 Jazzy 为例）
sudo apt update
sudo apt install ros-jazzy-rosbridge-server
# 启动 rosbridge（同时启动 rosapi）
source /path/to/ros_ws/install/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml重要提醒
必须同时安装 rosapi。ros-mcp-server 需要 rosbridgeserver 的 WebSocket 接口 和 rosapi 的内省服务（提供 getnodes、gettopics、getservices 等功能）。请使用 launch 文件 启动而非
ros2 run，否则所有 introspection 工具将因 “Service does not exist” 错误而失败。建议安装 ros-<distro>-rosbridge-suite 元包。ROS1 启动命令：
roslaunch rosbridge_server rosbridge_websocket.launch步骤三: 连接机器人
在 AI 客户端中输入以下指令即可连接：
Connect to the robot at <robot-ip>连接后可尝试探索 ROS 系统：
What topics and services are available on the robot?RobotMCP 平台架构
除核心服务器外，项目还提供了完整的 RobotMCP 平台。平台由三层组成：Server（托管 MCP 端点）、Modules（提供工具的插件包）和 Cloud（云服务处理初始设置）。
RobotMCP Server
基于 FastAPI 的 MCP 服务器，运行在本地或机器人上：
| 端点 | 传输方式 | 说明 |
|---|---|---|
POST /mcp | Streamable HTTP | 主 MCP 端点（推荐） |
GET /sse | SSE | 旧版端点（即将弃用） |
GET / | HTTP | 服务器信息 |
核心功能：
- 模块自动发现 - 启动时扫描
.gitmodules，读取各模块的pyproject.toml，自动安装依赖并调用模块的register()函数 - Cloudflare 隧道 - 将本地服务器暴露为
{your-robot}.robotmcp.ai，无需端口转发或防火墙更改 - OAuth 2.1 - 可选的认证机制，支持 PKCE、动态客户端注册和创建者权限控制
- CLI 守护进程 - 后台运行，支持 start、stop、status、verify 命令
ROS-MCP 模块
作为默认内置模块，提供全面的 ROS 工具集：
| 类别 | 能力 |
|---|---|
| Topics | 发布消息、订阅流、列出可用 topic |
| Services | 调用任意服务（含自定义类型） |
| Parameters | 读写 ROS 参数 |
| Nodes | 列出和检查运行中的节点 |
| Actions | ROS action 支持 |
| Images | 捕获和分析摄像头画面 |
| Connection | 管理 rosbridge 连接 |
| Robot config | 获取机器人规格信息 |
此外还注册了 resource（主题定义、服务模式、类型文档）和 prompt（数据分析、调试、机器人交互的系统提示词）。
自定义模块开发
模块为插件包，通过 integration.py 中的 register() 函数向服务器注册工具。
自定义模块目录结构
my-module/
├── pyproject.toml # 包名和依赖
└── my_module/
├── __init__.py
└── integration.py # register(mcp, **kwargs) 函数
# pyproject.toml 示例
[project]
name = "my-module"
version = "0.1.0"
dependencies = ["fastmcp>=2.0.0"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
# integration.py 示例
from fastmcp import FastMCP
def register(mcp: FastMCP, **kwargs) -> None:
@mcp.tool()
def my_tool(param: str) -> str:
"""Description of what this tool does."""
return f"Result: {param}"添加模块到服务器：
robotmcp-server add https://github.com/robotmcp/test-mcp-server.gitRobotMCP Cloud
位于 app.robotmcp.ai 的轻量级云服务，仅参与以下初始设置：
- 用户认证（基于 Supabase）
- Cloudflare 隧道创建和 DNS 配置
- 通过 Web 仪表盘进行服务器共享和访问管理
云服务仅在初始设置和服务管理阶段参与，不在 MCP 数据路径中 - 配置完成后，LLM 客户端直接通过 Cloudflare 隧道连接到本地服务器，数据不经过云端。
应用场景
- 工业机器人调试 - AI Agent 诊断工业机器人末端执行器异常，自动发现自定义 topic 和服务类型
- 自然语言操控 - 通过自然语言指令控制机器人执行复杂任务（导航、抓取等）
- 仿真集成 - 与 NVIDIA Isaac Sim、Gazebo 等仿真环境配合使用
- 多机器人协作 - 通过 MCP 协议管理多个机器人系统
评论