WiseVision ROS2 MCP Server

ROS2 MCP

ROS2 MCP 是一款开源（MPL-2.0）的 Model Context Protocol 服务，可让 AI Agent（Claude、Cursor、Codex 及其他任何 MCP 客户端）在运行中的机器人上列出、订阅和发布 ROS 2 话题，以及调用 ROS 2 服务和动作。它通过 rclpy 直接与 ROS 2 通信：无需 rosbridge，也无需更改机器人。传输方式：stdio（默认）、Streamable HTTP 和 SSE（MCP 规范已弃用）。

所有工具均免费且开源。如果需要帮助将其部署到实际设备上，可获取商业支持。

⚡ 快速开始（30 秒，Docker）

你需要 Docker 和一个 MCP 客户端。无需安装 ROS 2：镜像中已包含 ROS 2。

# Claude Code (use :humble for a ROS 2 Humble system). Read-only: the agent can look, not act.
claude mcp add ros2 -- docker run -i --rm -e ROS2_MCP_READONLY=1 wisevision/ros2_mcp:jazzy

对于其他任何 MCP 客户端：将 docker run -i --rm -e ROS2_MCP_READONLY=1 wisevision/ros2_mcp:jazzy 作为其 stdio 命令运行。然后询问：“列出 ROS 2 话题”和“从 /chatter 读取三条消息”。

手边没有机器人？先启动一个演示发布器：

docker run -d --name demo-robot ros:jazzy-ros-base bash -c \
  'source /opt/ros/jazzy/setup.bash && ros2 topic pub -r 2 /chatter std_msgs/msg/String "{data: hello from the robot}"'

更喜欢使用 uv？在已安装并配置 ROS 2 环境的机器上运行（服务需要 rclpy；请使用与你的发行版匹配的 Python，例如 Jazzy 使用 3.12）：

source /opt/ros/jazzy/setup.bash
uvx --python /usr/bin/python3 --from git+https://github.com/wise-vision/ros2_mcp mcp_ros_2_server

只有在希望 Agent 能够移动物体时，才移除 -e ROS2_MCP_READONLY=1（或 --read-only 标志）；请参阅安全性。针对特定客户端的配置（VS Code Copilot、Claude Desktop、Warp、Codex CLI、自定义消息）：安装指南。文档：wisevision.tech/docs。

Docker 官方 MCP 目录中的 mcp/ros2（截至撰写本文时已拉取 13,750 次）由 Docker 构建，版本落后于我们的发布：上次更新日期为 2026-02-04，且早于只读模式。wisevision/ros2_mcp 由本仓库的 CI 构建并推送，以上命令使用的正是这个镜像。

🧰 工具

24 个工具。⚠ 标记的工具可更改机器人状态；只读模式会移除这些工具。完整的生成版参考文档（含输入架构）位于 docs/generated/tools.md（CI 检查会确保它与代码保持同步）。

区域	工具
发现	ros2_topic_list、ros2_service_list、ros2_list_actions、ros2_interface_list、ros2_get_message_fields（消息类型的字段名称和类型）
话题	ros2_topic_subscribe、ros2_subscribe_multiple_topics（图像以 PNG 格式返回）、⚠ ros2_topic_publish、⚠ ros2_publish_multiple_topics（设置频率和持续时间）
服务	⚠ ros2_service_call
动作	⚠ ros2_send_action_goal（可选等待结果）、ros2_action_request_result、ros2_action_subscribe_feedback、ros2_action_subscribe_status、⚠ ros2_cancel_action_goal
感知	ros2_get_map_as_image（将 nav_msgs/OccupancyGrid 转换为 PNG）、ros2_get_pointcloud_as_bev（将 sensor_msgs/PointCloud2 转换为鸟瞰 PNG）
历史记录	ros2_get_messages_stored_in_influx_data_base（从 WiseVision Data Black Box 获取历史消息；它是基于 InfluxDB 的 Rosbag2 替代方案）
查看器应用	ros2_viewer_app、ros2_viewer_config、ros2_stream_start、ros2_stream_next、ros2_stream_next_image、ros2_stream_stop（适用于支持 Apps 的 MCP 客户端的交互式图像／点云／绘图查看器；流工具也可服务于无法渲染查看器的客户端）

另外还包括：四个内置提示词、话题的自动 QoS 选择、嵌套消息字段和自定义消息类型（启动前请先 source 你的包；参见安装指南）。

🧭 支持的 ROS 2 发行版

发行版	状态
Jazzy Jalisco（Ubuntu 24.04，Python 3.12）	支持。在 CI 中使用 ros:jazzy-ros-base 运行测试；Docker 镜像为 wisevision/ros2_mcp:jazzy。
Humble Hawksbill（Ubuntu 22.04，Python 3.10）	支持。在 CI 中使用 ros:humble-ros-base 运行测试；Docker 镜像为 wisevision/ros2_mcp:humble。
Iron、Kilted、Rolling	未经测试，也未发布。源码版本可能可用；我们不作保证。如果你需要支持这些版本，请提交 issue。

不支持 ROS 1（服务使用 rclpy）。Python 3.10 或更高版本。

🆚 对比

其他开源 ROS MCP 服务也已存在。它们各有取舍，请根据需求选择。以下信息来自各项目的 README、pyproject.toml 和 GitHub 页面，读取日期为 2026-10-14。

	ROS2 MCP（本仓库）	robotmcp/ros-mcp-server	LCAS/ros2_mcp
连接 ROS 的方式	rclpy，直接连接 ROS 2 图（在已加载 ROS 2 环境的地方运行，或在 Docker 镜像中运行）	rosbridge WebSocket；MCP 服务可以运行在与机器人不同的机器上	在你的 colcon 工作区中构建的 ROS 2 软件包
ROS 版本	ROS 2 Humble、Jazzy	ROS 1 和 ROS 2	ROS 2 Humble、Iron、Jazzy（根据其 README）
安装	Docker 镜像 wisevision/ros2_mcp，或通过 git 使用 uvx/uv	uvx ros-mcp（在 PyPI 上）	git clone、rosdep、colcon build；Docker Compose 搭配 SSE 端点
传输方式	stdio、Streamable HTTP、SSE	stdio、http、streamable-http（--transport）	文档中列出了 SSE 端点
只读模式	有：不注册可修改数据的工具，并通过测试确保分类正确	代码中未发现此类开关；工具带有 MCP readOnlyHint 注解	其 README 仅列出观测功能
发布 / 服务 / 动作	有，包括目标、结果、反馈、状态和取消	有（主题、服务和动作工具）	README 中未列出
节点和参数	目前还没有专用工具	有（节点和参数工具）	节点列表
图像和地图	将图像主题作为 PNG、占用栅格地图、点云鸟瞰图返回	图像工具	获取图像以进行 VLM 分析
许可证	MPL-2.0	Apache-2.0	Apache-2.0
GitHub 星标数	90	1,493	9

何时选择其他项目：如果你需要 ROS 1、节点或参数工具，或者希望 MCP 服务在机器人之外运行，而机器人端只暴露 rosbridge，请使用 robotmcp/ros-mcp-server。我们并不声称在各方面都更胜一筹。我们的优势包括：原生 rclpy 访问（Agent 与 DDS 之间无需桥接进程）、故障时默认拒绝的只读模式（只有经过明确审核、确认只读的工具才会在该模式下注册；新增工具未分类时测试会失败）、以 PNG 格式返回图像、地图和点云、完整的动作生命周期（目标、结果、反馈、状态、取消），以及按需提供商业支持。如果这里有错误或信息已过时？请提交 issue，我们会修正。

🗺️ 路线图（拟议中，尚未承诺）

用户提出但 ROS2 MCP 目前尚未提供的功能。没有时间表；请提交 issue 或在 Discussion 中投票，也可以付费支持其中一项。

• 参数工具：获取 / 设置 / 列出节点参数。
• TF 工具：坐标变换查询和坐标系树。
• Streamable HTTP 身份验证（Bearer 令牌或有文档说明的反向代理配置方案）。传输方式本身已在 #55 中实现；在身份验证功能推出前，请仅在回环地址或专用网络上使用。
• 节点工具（列出节点、节点信息）、Nav2 专用辅助工具、PyPI 软件包、ROS 1（暂不计划）。

🤖 面向 AI Agent

如果你是使用此服务的 Agent（或正在构建 Agent）：

• 先发现，再行动。 在发布消息、调用服务或发送动作目标之前，先调用 ros2_topic_list、ros2_service_list、ros2_list_actions 和 ros2_interface_list，然后针对确切的消息类型调用 ros2_get_message_fields。不要猜测字段名称。
• 优先只读。 如果 list_tools 中没有 ros2_topic_publish、ros2_service_call、ros2_send_action_goal，说明操作员以只读模式启动了服务；不要尝试绕过限制。
• 会改变状态的工具可能会让真实机器移动。 调用 ⚠ 工具前，先向用户确认意图；从较小的数值和较短的持续时间开始，并记得使用 ros2_cancel_action_goal。
• 容器刚启动后，图可能尚不完整（DDS 发现过程）。如果缺少预期的主题，请重试一次，再判断它不存在；请参阅 DDS 发现预热。
• 机器可读参考资料： docs/generated/tools.json（每个工具及其输入架构）、server.json（MCP 注册清单）、AGENTS.md（仓库结构、构建、测试和添加工具的方法）、wisevision.tech/llms.txt。

🏢 商业支持与集成

ROS2 MCP 是基于 MPL-2.0 的免费软件：你可以将它用于商业产品，无需征求我们的同意。本节内容不会改变这一点。

如果你计划将它用于真实机器人或机器人集群，并且需要公共问题跟踪器之外的支持，维护团队 WiseVision 可以提供以下帮助：

• 集成支持：让服务适配你的技术栈、消息类型和 QoS 限制。
• 定制工具和提示词：为你自己的接口编写处理程序，扩展内置的主题、服务和动作工具集。
• 优先修复：针对阻碍你部署的缺陷，按计划处理，而不是排入待办事项队列。

联系我们： 使用 wisevision.tech/contact 上的表单（选择 ROS2 MCP on a real fleet），或发送邮件至 [email protected]。请先说明问题：使用的机器人、技术栈以及遇到的阻碍。我们会按项目评估并报价；目前没有价目表，请联系我们。其他用户也能从中受益的问题，请发布到 Discussions 或 issues。

想先看看真实数据上的效果？叉车 rosbag 演示 会回放一段仓库叉车记录，并演示如何在约 10 分钟内调用三次 MCP。

⚙️ 安装

请按照安装指南逐步完成安装：

• 🧩 在 Visual Studio Code Copilot 中安装
• 🤖 在 Claude Desktop 中安装
• 💻 在 Warp 中安装
• 🐳 在本地构建 Docker 镜像

🔒 安全：只读模式

连接到真实机器人的 Agent 可能会让它移动。以只读模式启动服务，让 Agent 可以观察但不能操作：

ROS2_MCP_READONLY=1 uv run mcp_ros_2_server      # env var
uv run mcp_ros_2_server --read-only              # or CLI flag
docker run -i --rm -e ROS2_MCP_READONLY=1 mcp/ros2

在只读模式下，会改变机器人状态的工具完全不会注册：它们不会出现在 list_tools 中，调用时会返回 Unknown tool 错误。隐藏的工具包括： ros2_topic_publish、ros2_publish_multiple_topics、ros2_service_call、ros2_send_action_goal、ros2_cancel_action_goal。 只读模式采用默认拒绝策略：仅注册经过明确审查、确认只读的工具（列于 server/tool_safety.py 中）；如果添加新工具时未对其进行分类，测试就会失败。 ros2_service_call 会被隐藏，因为服务无法判断任意服务是否具有副作用。

🌐 Streamable HTTP（远程 / 多客户端）

stdio 是默认传输方式，无需网络。若要为多个客户端提供服务，或连接另一台机器上的客户端，请使用 Streamable HTTP，这是当前 MCP 规范定义的传输方式（较旧的 sse 传输方式已被规范弃用，仅为现有客户端保留）。

uv run mcp_ros_2_server --transport streamable-http          # http://127.0.0.1:8123/mcp
claude mcp add --transport http ros2 http://127.0.0.1:8123/mcp   # Claude Code; other clients: use the URL

Docker（仅在回环地址上发布端口）：

docker run --rm -p 127.0.0.1:8123:8123 \
  -e ROS2_MCP_TRANSPORT=streamable-http -e ROS2_MCP_HOST=0.0.0.0 -e ROS2_MCP_READONLY=1 \
  wisevision/ros2_mcp:jazzy                                 # http://127.0.0.1:8123/mcp

容器内需要设置 ROS2_MCP_HOST=0.0.0.0（绑定到回环地址无法通过 -p 访问）；-p 中的 127.0.0.1: 可确保服务不会暴露到网络中。如果首次调用工具时未列出任何话题，说明 DDS 发现未能穿过容器边界；在 Linux 上，通常可通过 --network host（然后移除 -p 和 ROS2_MCP_HOST）解决，但具体取决于你的 DDS 和网络设置。

选项	环境变量	默认值
--transport	ROS2_MCP_TRANSPORT	stdio	stdio、streamable-http、sse
--host	ROS2_MCP_HOST	127.0.0.1	容器内使用 0.0.0.0
--port	ROS2_MCP_PORT	8123
--allowed-host HOST[:PORT]	ROS2_MCP_ALLOWED_HOSTS	仅限绑定回环地址时的 localhost	接受的 Host 标头（防止 DNS 重绑定）；可重复指定 / 以逗号分隔；* 匹配任意端口
--stateless、--json-response		关闭	不保留各客户端的会话状态；返回普通 JSON，而非事件流

⚠️ 此服务没有身份验证。 任何能够访问该端口的人都能使用所有工具，包括向话题发布消息。请将服务限制在回环地址或专用网络中；如需扩大访问范围，请在前面部署带身份验证的反向代理，并考虑启用只读模式。服务绑定到非回环地址时会打印警告。

🧭 DDS 发现预热（Docker）

如果容器启动后立即进行的首次工具调用返回的话题 / 服务列表不完整，DDS 发现可能仍在进行中。 服务器会在容器环境中的首次工具调用时执行一次预热；可通过以下选项调整：

• MCP_ROS_DISCOVERY_STABLE_SEC（默认值：1.0）
• MCP_ROS_DISCOVERY_TIMEOUT_SEC（默认值：5.0）
• 设置 MCP_ROS_DISCOVERY_WARMUP=false 可禁用

🤖 提示词

📘 想创建自定义提示词？查看此处的指南

📊 base.ros2-topic-echo-and-analyze

订阅 ROS2 话题，在指定时长内收集消息，并对收集到的数据进行统计分析。

➡️ 如果只有一个可用话题，可自动检测。分析数值字段的消息速率、数量和统计数据。

🔄 base.ros2-topic-relay

订阅一个 ROS2 话题，并将消息重新发布到另一个话题，可选择进行转换。

➡️ 支持原样转发、速率限制和基于变化的过滤。

🏥 base.ros2-node-health-check

检查预期的 ROS2 话题和服务是否可用且运行正常，并可选择监控发布速率。

➡️ 提供全面的健康状况报告，包含状态指示和建议。

🔍 base.ros2-topic-diff-monitor

比较两个 ROS2 话题，并通过详细的逐字段分析报告消息差异。

➡️ 适用于比较原始传感器数据与经过滤或处理的数据，也可用于验证话题同步情况。

ROS2 MCP 还提供包含更多提示词的提示词扩展：点击此处查看

💡 不知道什么是提示词？查看 MCP 规范。

注意： 使用自定义（非默认）类型调用服务时，请在启动服务器前 source 定义该类型的软件包。

🎬 演示

🚀 使用提示词执行无人机任务

🌍 真实案例

想在仿真环境中试用吗？请参阅 Gazebo 无人机演示。

🐞 调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/ros2_mcp run mcp_ros_2_server

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL，开始调试。

🤝 参与贡献

欢迎贡献。查看未解决的问题，提交拉取请求，或先来我们的 Discord 讨论想法。开发环境设置和测试请参阅 AGENTS.md。参与即表示你同意我们的行为准则。

📚 起源

我们构建此服务，旨在让 AI 辅助的 ROS 2 开发快速而可靠。在内部，我们需要一种简单的方式，让 Agent 能够发现消息类型、发布和订阅主题并调用服务，同时避免样板代码和不稳定的网络连接。由此，我们确立了几个核心设计目标：

• 处理所有 ROS 2 消息类型（包括嵌套字段），让 Agent 能够编写和测试任意代码
• 集成主题发布/订阅和服务调用，以端到端验证行为
• 与 VS Code 中的 GitHub Copilot 及其他 MCP 客户端无缝协作
• 使用简单的 stdio 传输，避免网络复杂性

在内部试用后，我们以开源方式发布了此项目（MPL-2.0），帮助更广泛的 ROS 2 社区借助 AI 更快地开展工作。如今，它不仅适用于开发，还可用于控制机器人、运行 QoS 实验，以及分析实时数据和机器人/集群状态。项目在积极维护中，会根据用户反馈定期推出功能和改进。如果此项目对你有帮助，欢迎在讨论区分享你的使用案例！