rosbridge-mcp

rosbridge-mcp 是一个模型上下文协议服务器，它通过标准的 rosbridge v2 协议（WebSocket + JSON），将 AI 代理（Claude Desktop、Cursor、VS Code 以及任何其他 MCP 客户端）连接到运行 ROS 2 的机器人。您在机器人或 ROS 机器上运行 rosbridge_server；此 MCP 服务器通过网络连接到它，并公开了 11 个工具，让 AI 可以观察话题、检查 ROS 图和 TF 树、通过机器人摄像头查看、发布消息、调用服务以及驱动 ROS 2 动作——在运行 AI 客户端的机器上无需安装 ROS。

架构

+--------------------+   stdio (MCP)   +----------------+   WebSocket/JSON   +------------------+   DDS   +---------+
|  AI client         | <-------------> | rosbridge-mcp  | <----------------> | rosbridge_server | <-----> |  ROS 2  |
|  (Claude, Cursor,  |                 |  (this server) |    rosbridge v2    |  (on the robot)  |         |  graph  |
|   VS Code, ...)    |                 |                |      protocol      |                  |         |         |
+--------------------+                 +----------------+                    +------------------+         +---------+

Related MCP server: ROS2 MCP Server

快速开始（60秒）

pip install git+https://github.com/hieutachi/rosbridge-mcp.git

或者，发布后：pip install rosbridge-mcp（PyPI ——即将推出）。

添加到您的 MCP 客户端配置中（有关确切文件位置，请参阅下面的各客户端指南）：

{
  "mcpServers": {
    "rosbridge": {
      "command": "rosbridge-mcp",
      "env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
    }
  }
}

然后询问您的代理：“机器人有哪些话题？”

选择您的路径

选择最适合您的指南——每份指南都是独立的，您无需先阅读 README 的其余部分：

工具

共 11 个工具。所有工具均返回 JSON。消息和参数负载使用与 rosbridge 相同的 ROS 消息 JSON 表示形式（字段名称与 .msg/.srv/.action 定义匹配）。

list_topics

列出所有话题及其消息类型。无参数。

{"topics": [
  {"name": "/chatter", "type": "std_msgs/msg/String"},
  {"name": "/cmd_vel", "type": "geometry_msgs/msg/Twist"},
  {"name": "/scan",    "type": "sensor_msgs/msg/LaserScan"}
]}

list_nodes

列出所有运行中的节点。无参数。

{"nodes": ["/talker", "/listener", "/rosapi"]}

list_services

列出所有可用的服务。无参数。

{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}

get_topic_snapshot

订阅一个话题，收集消息，取消订阅。参数：topic（必需），count（默认 1），timeout 秒（默认 5.0），msg_type（可选，通常由 rosbridge 自动检测）。

输入：{"topic": "/chatter", "count": 2, "timeout": 3.0}

{"topic": "/chatter", "requested": 2, "received": 2,
 "messages": [{"data": "Hello World: 41"}, {"data": "Hello World: 42"}],
 "timed_out": false}

如果话题静默，received 将小于 requested 且 timed_out 为 true——该工具永远不会阻塞超过 timeout 时间。

publish_message （可更改）

通告一个话题并发布一条 JSON 消息。参数：topic，msg_type（完整的 ROS 2 类型，例如 geometry_msgs/msg/Twist），message（匹配该类型的 JSON 对象）。

输入：

{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist",
 "message": {"linear": {"x": 0.1, "y": 0.0, "z": 0.0},
             "angular": {"x": 0.0, "y": 0.0, "z": 0.2}}}

输出：{"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}

call_service （可更改）

调用任何 ROS 服务。参数：service（必需），args（JSON 对象，默认 {}），timeout 秒（默认 10.0）。

输入：{"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}

{"service": "/rosapi/topic_type", "success": true,
 "values": {"type": "sensor_msgs/msg/LaserScan"}}

失败时，工具返回 {"success": false, "error": "..."} 而不是抛出异常。

send_action_goal （可更改）

向 ROS 2 动作服务器（导航、机械臂运动等）发送一个目标。参数：action_name，action_type（包含 /action/ 的完整类型，例如 nav2_msgs/action/NavigateToPose），goal（JSON 对象，默认 {}），timeout 秒（默认 30，上限为 120），wait_for_result（默认 true）。

输入：{"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}}

{"action": "/fibonacci", "goal_id": "send_action_goal:7", "success": true,
 "status": 4, "status_text": "succeeded",
 "values": {"sequence": [0, 1, 1, 2, 3, 5]},
 "last_feedback": {"partial_sequence": [0, 1, 1, 2, 3]}}

当 wait_for_result: false 时，工具立即返回 {"goal_id": ..., "result_pending": true}——将该 goal_id 传递给 cancel_action_goal 可稍后停止该目标。需要支持 ROS 2 动作的 rosbridge_suite 版本；针对较旧的 rosbridge，工具返回建议升级的错误消息，而不是挂起。

cancel_action_goal （可更改）

取消先前发送的动作目标。参数：action_name，goal_id（来自 send_action_goal）。

输出：{"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}

get_tf_tree

通过短暂监听 /tf 和 /tf_static 来抓取机器人 TF（坐标变换）树的快照。参数：timeout 秒（默认 2.0，上限为 10）。

{"frame_count": 3,
 "frames": {
   "base_link": {"parent": "odom", "translation": {"x": 1.0, "y": 0.0, "z": 0.0},
                  "rotation": {"x": 0, "y": 0, "z": 0, "w": 1}, "source": "dynamic"},
   "laser":     {"parent": "base_link", "...": "...", "source": "static"}},
 "tree": {"odom": ["base_link"], "base_link": ["laser"]},
 "roots": ["odom"]}

get_camera_image

从摄像头话题获取一帧图像，编码为 base64，以便具有视觉能力的模型可以看到机器人所看到的内容。参数：topic（优先使用 sensor_msgs/msg/CompressedImage 类型的话题，例如 /camera/image_raw/compressed），timeout 秒（默认 5.0，上限为 30）。

输出：{"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234}（原始 Image 话题还会返回 width/height/encoding）。超过 4 MB 的帧不会返回——该工具会返回元数据以及一条建议使用压缩话题的错误消息。

get_connection_status

报告连接状态和只读模式。无参数。

{"url": "ws://localhost:9090", "connected": true,
 "connected_since_unix": 1786903978.1, "active_subscriptions": [],
 "pending_service_calls": 0, "readonly": false}

示例对话

您： 机器人现在看到了什么？

代理： （调用 list_topics，找到类型为 sensor_msgs/msg/LaserScan 的 /scan，然后调用 get_topic_snapshot，参数为 {"topic": "/scan", "count": 1}） 激光扫描仪报告了 360 个距离读数。最近的障碍物大约在 0.4 米外，位于左侧约 90° 方向；正前方至少 2.5 米内畅通无阻。

您： 好的，让它慢慢向前开一会儿。

代理： （调用 publish_message，参数为 {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}） 已发布 0.1 m/s 的前进速度命令。需要停止时请告诉我，我将发布零速度。

用于视觉与具身 AI

其中两个只读工具专门用于将视觉语言模型锚定在机器人的物理现实中：

• get_camera_image 将真实的摄像头帧作为 base64 返回——具有视觉能力的模型（Claude、GPT-4o 或 VLA 策略前端）在决定做什么之前，可以直观地通过机器人的摄像头观察。

• get_tf_tree 为模型提供机器人的空间骨架——存在哪些坐标系（map、odom、base_link、camera、gripper）以及它们之间的相对位置关系。

结合 get_topic_snapshot（激光雷达、里程计、关节状态）和 send_action_goal（导航、操作），这覆盖了视觉和动作代理所需的观察→推理→行动循环，通过简单的 WebSocket 实现，模型端无需安装 ROS。两个感知工具均在只读模式下工作，因此您可以安全地运行“只看不碰”的代理。

配置

安全

让语言模型向实体机器人发布 /cmd_vel 是一个真实存在的风险。设置 ROSBRIDGE_MCP_READONLY=true 以运行只读模式：publish_message、send_action_goal 和 cancel_action_goal 将被拒绝，并且 call_service 仅允许一个固定的允许列表，包含已知的只读 /rosapi 自省服务（topics、nodes、services、types、get_param、get_time 等）——任何不在列表中的内容，包括未知的未来 /rosapi 服务，都将被拒绝。只读感知工具（get_topic_snapshot、get_tf_tree、get_camera_image）继续工作。我们强烈建议在实体硬件上以只读模式启动——请参阅完整的实体机器人安全清单以及 SECURITY.md 中的部署安全模型。

隐私与法律

无遥测，无数据收集。 审计日期（2026-08）：此包打开的唯一网络连接是到您配置的 ROSBRIDGE_URL 的 WebSocket——没有分析功能、无电话回家、无崩溃报告、无隐藏的 HTTP 调用，并且代码中不包含将消息内容记录到磁盘的功能。捆绑的模拟服务器仅绑定到 127.0.0.1。工具返回的机器人数据仅发送到您的 MCP 客户端（该客户端会将其转发给您选择的 LLM——该部分由您控制，而非我们）。

许可证合规性。 所有运行时和传递依赖项均携带与本项目 MIT 许可证兼容的许可证——直接依赖项：fastmcp（Apache-2.0）、websockets（BSD-3-Clause）；关键传递依赖项：mcp（MIT）、pydantic（MIT）、starlette（BSD-3-Clause）、httpx（BSD-3-Clause）、anyio（MIT）、cryptography（Apache-2.0/BSD-3）。一个传递依赖项 certifi 是 MPL-2.0——这是一种文件级别的版权左派许可证，仅适用于对 certifi 自身文件的修改，并且与 MIT 的使用和重新分发兼容。依赖树中没有任何 GPL/AGPL/专有代码，并且此仓库中的所有代码均为此项目编写的原创作品。

常见问题

我需要在运行 AI 客户端的地方安装 ROS 吗？ 不需要。只需要 Python 3.10+。ROS 和 rosbridge 运行在机器人上（或在 Docker 中，或在模拟器中）；此服务器通过 WebSocket 与它们通信。

它适用于 ROS 1 吗？ rosbridge v2 协议是相同的，因此基本操作也适用于 ROS 1 的 rosbridge_server——使用 ROS 1 类型名称（std_msgs/String）。但 CI 中仅测试了 ROS 2。

Agent 提示无法连接。 请检查 rosbridge 是否正在运行（ros2 launch rosbridge_server rosbridge_websocket_launch.xml），ROSBRIDGE_URL 是否指向正确的主机/端口，以及端口 9090 是否可达（防火墙）。docs/ 中的每个指南都包含故障排除部分。

我可以在没有机器人或模拟器的情况下试用吗？ 可以 — python -m rosbridge_mcp.mock_server 9090 会启动一个包含预设话题的虚假 rosbridge，然后将 ROSBRIDGE_URL 指向 ws://localhost:9090 即可。

我的数据会被发送到任何地方吗？ 服务器仅连接到您配置的 ROSBRIDGE_URL。话题数据会返回给您的 MCP 客户端，再由客户端转发给您使用的任何 LLM — 请根据情况处理传感器数据。

路线图

分阶段计划，包含每个阶段的目标、交付物以及所需资源：请参见 ROADMAP.md。亮点：v0.2 动作客户端 + TF + 摄像头快照（已在 v0.2.0 中完成），v0.3 HTTP 传输 + Docker 镜像 + rosbridge 认证/TLS，v0.4 多机器人集群 + MCP 资源（URDF/地图），v1.0 稳定 API + 官方 MCP 注册表收录 + Gazebo/Isaac Sim 示例。

支持本项目

rosbridge-mcp 由一人兼职开发和维护，目前处于早期阶段。现有功能真实可靠且经过测试：11 个工具，涵盖话题、服务、ROS 2 动作、TF 和摄像头快照；43 个自动化测试在每次提交时于 CI 中运行；为 5 种用户路径提供按场景划分的文档；一个只读安全模式及服务允许列表；以及一个经过审计的零遥测代码库。

以下是路线图所需实现目标的真实叙述：

• v0.3（部署与安全）： 兼职开发数周，一台用于 Docker 镜像构建的小型云 VM 或自托管运行器，以及最重要的 — 一名关注安全的审查者来审核 rosbridge 认证/TLS 层。

• v0.4（集群）： 访问 2 个或多个同时运行的机器人或模拟器实例，以及来自真实机器人实验室的设计反馈（正在寻找学术或工业试点合作伙伴）。

• v1.0（稳定与生态）： 持续的维护者时间（每周 2 天，持续一个季度），一台用于 Isaac Sim 验证的 RTX 级 GPU 工作站 — 整个路线图中主要的硬件需求 — 以及可选的一台低成本机器人（$1–3k）用于硬件在环 CI。

您可以按以下方式提供帮助（按投入精力递增排序）：

1. 为仓库加星 — 知名度确实有助于早期项目吸引贡献者。

2. 在您的机器人或模拟器上试用，并提交一个包含您的 ROS 发行版和 rosbridge 版本的问题 — 兼容性报告是提升鲁棒性最经济的方式。

3. 贡献 PR — docs/development.md 可在 10 分钟内解释代码库，每个路线图项目都可认领。

4. 赞助或合作 — 如果您的实验室或公司可以提供模拟器时间、硬件、GPU 工作站或资助开发时间，请通过 github.com/hieutachi 联系。

相关资源

如果您正在进入机器人领域，Robotics RL & UAV ebook 是作者提供的配套学习资源，涵盖强化学习和无人机机器人技术。

贡献

欢迎贡献！请参见 CONTRIBUTING.md 和开发指南。请确保签署您的提交（DCO）。

许可证

MIT — 请参见 LICENSE。依赖项许可证宽松且兼容：fastmcp（Apache-2.0），websockets（BSD-3-Clause）。无 GPL/AGPL 依赖。

越南语摘要

rosbridge-mcp 是一个 MCP 服务器，通过 rosbridge 协议（WebSocket + JSON）在 AI agent（Claude Desktop、Cursor、VS Code 等）和运行 ROS 2 的机器人之间建立桥梁。无需在运行 AI 客户端的机器上安装 ROS。

文档按场景划分 — 在 docs/ 目录中为您选择正确的指南：

• 使用 Claude Desktop — Windows/macOS/Linux 上的逐步 JSON 配置

• 使用 Cursor / VS Code — 在编辑器中配置 mcp.json

• 还没有机器人 — 使用 Docker（ros:humble + rosbridge）或 TurtleBot3/Gazebo 试用，或使用附带的模拟服务器

• 有真实机器人 — 安全检查清单：先启用 ROSBRIDGE_MCP_READONLY=true，读取 /odom、/scan 以了解机器人，然后才开放发布 /cmd_vel 的权限

• 开发者 — 代码架构、添加新工具的方法、使用模拟（无需 ROS）运行测试

11 个工具：list_topics、list_nodes、list_services、get_topic_snapshot、publish_message、call_service、send_action_goal、cancel_action_goal、get_tf_tree、get_camera_image、get_connection_status。在处理真实机器人时，启用 ROSBRIDGE_MCP_READONLY=true 以阻止所有写入操作（发布、动作）——读取工具（TF、摄像头、话题）仍可正常使用。

作者提供的配套学习资源：Robotics RL & UAV ebook — 关于强化学习和无人机机器人的电子书。