{{htmlmetatags>metatag-robots=()
metatag-keywords=(ros,mcp-server,modelcontextprotocol,ros2,ros-mcp-server,robot operating system,large language model,rosbridge,robotmcp)
metatag-description=(ROS-MCP-Server 通过 MCP 协议实现大语言模型与 ROS/ROS2 系统的双向集成，支持自然语言控制机器人、实时传感器数据流和零代码修改集成。)
}}

====== ROS-MCP-Server: LLM与ROS系统的MCP桥梁 ======

**ROS-MCP-Server** 是一个开源项目，实现了大语言模型与机器人操作系统之间的双向集成。它通过 MCP 协议与 LLM 端通信，通过 **rosbridge** WebSocket 协议连接 ROS 系统，充当协议翻译层。

<box>项目地址：[[https://github.com/robotmcp/ros-mcp-server]] | Stars: 1291 | 许可证: Apache 2.0 | 主页：[[https://robotmcp.ai]]</box>

===== 核心能力 =====

  * **自然语言控制机器人**  - 将对话式命令转换为 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：

<code bash>
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 添加 MCP 服务器到 Claude Code
claude mcp add ros-mcp -- uvx ros-mcp --transport=stdio
</code>

支持的其他客户端包括：

^ 客户端 ^ 说明 ^
| Codex CLI | OpenAI 的 CLI 代理 |
| Gemini CLI | Google 的 CLI |
| Claude Desktop | Anthropic 桌面应用 |
| ChatGPT | OpenAI 桌面应用 |
| Cursor | AI 增强 IDE |

==== 步骤二: 启动 Rosbridge ====

在机器人端安装并启动 rosbridge_server：

<code bash>
# 安装 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
</code>

<box 80% round orange|重要提醒>必须同时安装 **rosapi**。ros-mcp-server 需要 rosbridge_server 的 WebSocket 接口 **和** rosapi 的内省服务（提供 get_nodes、get_topics、get_services 等功能）。请使用 **launch 文件** 启动而非 ``ros2 run``，否则所有 introspection 工具将因 "Service does not exist" 错误而失败。建议安装 ``ros-<distro>-rosbridge-suite`` 元包。</box>

ROS1 启动命令：
<code bash>
roslaunch rosbridge_server rosbridge_websocket.launch
</code>

==== 步骤三: 连接机器人 ====

在 AI 客户端中输入以下指令即可连接：
<code text>
Connect to the robot at <robot-ip>
</code>

连接后可尝试探索 ROS 系统：
<code text>
What topics and services are available on the robot?
</code>

===== 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()`` 函数向服务器注册工具。

<box>自定义模块目录结构</box>
<code text>
my-module/
├── pyproject.toml       # 包名和依赖
└── my_module/
    ├── __init__.py
    └── integration.py   # register(mcp, **kwargs) 函数
</code>

<code toml>
# pyproject.toml 示例
[project]
name = "my-module"
version = "0.1.0"
dependencies = ["fastmcp>=2.0.0"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
</code>

<code python>
# 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}"
</code>

添加模块到服务器：
<code bash>
robotmcp-server add https://github.com/robotmcp/test-mcp-server.git
</code>

==== RobotMCP Cloud ====

位于 ``app.robotmcp.ai`` 的轻量级云服务，仅参与以下初始设置：

  * 用户认证（基于 Supabase）
  * Cloudflare 隧道创建和 DNS 配置
  * 通过 Web 仪表盘进行服务器共享和访问管理

<box>云服务仅在初始设置和服务管理阶段参与，**不在 MCP 数据路径中** - 配置完成后，LLM 客户端直接通过 Cloudflare 隧道连接到本地服务器，数据不经过云端。</box>

===== 应用场景 =====

  * **工业机器人调试**  - AI Agent 诊断工业机器人末端执行器异常，自动发现自定义 topic 和服务类型
  * **自然语言操控**  - 通过自然语言指令控制机器人执行复杂任务（导航、抓取等）
  * **仿真集成**  - 与 NVIDIA Isaac Sim、Gazebo 等仿真环境配合使用
  * **多机器人协作**  - 通过 MCP 协议管理多个机器人系统

===== 参考链接 =====

  * [[https://github.com/robotmcp/ros-mcp-server|GitHub 仓库]]
  * [[https://robotmcp.ai/architecture|RobotMCP 架构文档]]
  * [[https://docs.devin.ai/work-with-devin/deepwiki-mcp|DeepWiki MCP 文档]]
  * [[https://modelcontextprotocol.io/|MCP 协议官方文档]]