/ 目录 / 演练场 / ros-mcp-server
● 社区 robotmcp ⚡ 即开即用

ros-mcp-server

作者 robotmcp · robotmcp/ros-mcp-server

让 Claude 或 GPT 驱动一个 ROS 连接的机器人——发布主题、调用服务、读取传感器——通过 rosbridge,无需改代码。

robotmcp/ros-mcp-server 通过 rosbridge 将 AI 模型连接到 ROS 1 和 ROS 2 机器人。发布到主题、订阅、调用服务和动作、设置参数、读取传感器数据。支持包括 Humble 和 Jazzy 在内的多个 ROS 发行版。

为什么要用

核心特性

实时演示

实际使用效果

ros.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ros": {
      "command": "uvx",
      "args": [
        "ros-mcp-server"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "ros": {
      "command": "uvx",
      "args": [
        "ros-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "ros": {
      "command": "uvx",
      "args": [
        "ros-mcp-server"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "ros": {
      "command": "uvx",
      "args": [
        "ros-mcp-server"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "ros",
      "command": "uvx",
      "args": [
        "ros-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "ros": {
      "command": {
        "path": "uvx",
        "args": [
          "ros-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add ros -- uvx ros-mcp-server

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: ros-mcp-server

如何从聊天中驱动一个模拟机器人

👤 ROS 初学者、机器人开发者原型测试行为 ⏱ ~30 min intermediate

何时使用: 你想快速测试高层级的机器人行为。

前置条件
  • ROS 2(Humble/Jazzy)或 ROS 1 运行中 — Docker 容器中的 Humble 非常适合快速启动
  • 已安装 rosbridge_suite 并运行中 — ros2 launch rosbridge_server rosbridge_websocket_launch.xml
  • Python 3.10+ + uvx — brew install [email protected] uv
步骤
  1. 连接到 rosbridge
    使用 ROSBRIDGE_URL=ws://localhost:9090 配置 MCP 并验证连接。✓ 已复制
    → 返回活跃主题列表
  2. 移动机器人
    发布到 /cmd_vel 一条 Twist 消息,以 0.2 m/s 向前移动 3 秒钟,然后停止。✓ 已复制
    → 机器人在模拟中移动
  3. 读取传感器
    订阅 /scan 2 秒钟并报告 1m 内的障碍物。✓ 已复制
    → 范围数据摘要

结果: 一个实时响应自然语言命令的机器人。

注意事项
  • 发送过快的速度命令会使机器人崩溃/翻倒 — 在你的提示中限制命令速率;从小速度开始
  • 不安全的自主性——没有地理围栏 — 始终先在模拟中运行(Gazebo);没有硬件紧急停止不要连接到物理机器人

如何生成自然语言机器人健康摘要

👤 机器人运维团队 ⏱ ~15 min beginner

何时使用: 你想快速获得'机器人在做什么'的状态。

步骤
  1. 列出主题
    列出所有活跃主题。✓ 已复制
    → 主题目录
  2. 采样关键传感器
    分别订阅 /battery_state 和 /odom 3 秒钟;进行汇总。✓ 已复制
    → 电池百分比 + 位置摘要
  3. 检查参数
    获取 /navigation.max_velocity 的值。✓ 已复制
    → 参数值

结果: 操作员友好的机器人状态摘要。

如何从聊天中调用 ROS 动作(例如导航到位置)

👤 机器人开发者测试导航栈 ⏱ ~15 min intermediate

何时使用: 你想在不写客户端的情况下触发一个目标。

步骤
  1. 发送目标
    调用动作 /navigate_to_pose,目标为 x=2.0 y=1.0 yaw=0。✓ 已复制
    → 目标已接受,反馈流式传输
  2. 监控反馈
    流式传输反馈直到目标达成或 30 秒钟过去。✓ 已复制
    → 进度 + 结果

结果: 无需写客户端的导航测试。

注意事项
  • rosbridge 动作支持因版本而异 — 使用 ROS 2 + rosbridge 2.x 以获得最佳动作覆盖

组合

与其他 MCP 搭配,撬动十倍杠杆

将机器人运行日志记录到磁盘以供后续分析

订阅 /odom 60 秒钟并将轨迹写入 /logs/run-2026-04-14.csv。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_topics 发现机器人 free
publish_topic topic: str, type: str, msg: obj 命令机器人 free
subscribe_topic topic: str, duration_s?: int 读取传感器数据 free
call_service service: str, request: obj 向机器人进行单次 RPC 调用 free
send_action_goal action: str, goal: obj 长运行任务(导航、操纵) free
get_param name: str 检查配置 free
set_param name, value 在运行时调优 free

成本与限制

运行它的成本

API 配额
无——本地 rosbridge WebSocket
每次调用 Token 数
Topic 消息可能很大(图像、点云);避免将高带宽主题流式传输到 LLM
费用
免费
提示
永远不要将图像或点云主题订阅到 LLM——先在机器人端进行汇总。

安全

权限、密钥、影响范围

最小权限: 到 rosbridge WebSocket 的网络访问
凭据存储: 默认无;非本地使用时,在 rosbridge 后面放置身份验证
数据出站: ROS 主题流向 LLM 提供商——将传感器数据视为流向第三方
切勿授予: 不要将 rosbridge 暴露到公网 未配备硬件紧急停止不要授予自主性

故障排查

常见错误与修复

无法连接到 rosbridge

确保 rosbridge_server 正在运行且可在该 URL 访问。对于 ROS 2:ros2 launch rosbridge_server rosbridge_websocket_launch.xml

验证: nc -vz localhost 9090
Topic 发布被拒绝——未知类型

传递确切的消息类型(例如 geometry_msgs/msg/Twist)。使用 list_topics 查看已注册的类型。

动作反馈不流式传输

较旧的 rosbridge 版本对动作的支持不稳定。升级到 2.x。

高带宽主题导致代理崩溃

不要通过 LLM 订阅 /camera/image_raw 或 /velodyne_points。在机器人端进行汇总。

替代方案

ros-mcp-server 对比其他方案

替代方案何时用它替代权衡
rosa (NASA JPL)你想要一个基于 LangChain 的 ROS 代理,而不是 MCP不同的架构;不可插入 Claude Desktop

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills