Skip to main content
Glama
Sign In
ros2-inspector

ros2-inspector

by XuChen-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ros2-inspector

English | 简体中文

PyPI ROS2 Read-only Python MCP License

Let your AI inspect your ROS 2 system. This is an MCP Server: ask "how is the system doing?" in natural language and the AI picks the right read-only commands, correlates the outputs, and hands you a conclusion. Works on the local machine, over ssh to headless boards, and inside docker containers.

  MCP host (Claude Code / Qoder / Cursor / Claude Desktop…)
                      │ MCP protocol (stdio)
                      ▼
       ros2-inspector MCP (pure Python, zero ROS deps)
                      │ read-only commands (local / ssh / docker exec)
                      ▼
                ROS 2 system (DDS network)

The problem it solves

  • Answering "what is the system doing?" means jumping between a dozen commands — ros2 node list, node info, topic info -v, topic echo, topic hz, param list… — none of which are memorable;

  • Every step's raw output has to be read and correlated by hand;

  • ROS often lives on headless boards, remote servers, or inside containers, so you have to ssh in first.

ros2-inspector hands all of that to the AI: say "what is the robot arm on the board doing?" and it takes the overview → drills into suspects → verifies → concludes. Monitoring tools return semantic verdicts ("stable 10 Hz" / "intermittent: 2 gaps over 2 s"), not walls of raw numbers.

Related MCP server: k8s-readonly-mcp

Quick start

Prerequisite: uv (the only dependency); no ROS installation required on this machine.

Add to your MCP host (Claude Code / ZCode: workspace .mcp.json; Claude Desktop: claude_desktop_config.json; Qoder / Cursor: paste in settings):

{
  "mcpServers": {
    "ros2-inspector": {
      "command": "uvx",
      "args": ["ros2-inspector-mcp"]
    }
  }
}

Then just ask:

"Analyze the current system state" · "Which nodes are running?" · "Is /joint_states healthy?" · "What is the arm on the board doing?"

Remote inspection (ssh / containers)

ROS living on a headless board, a remote server, or in a container? Just say it in the conversation:

"Register a target: 192.168.1.50, user ubuntu, password xxx — that's my lab car host"

The AI shows a registration preview and writes it only after your confirmation (add_target); before first use it connects, shows you the identity card (hostname / OS / ROS distro / host-key fingerprint) and waits for your go-ahead (check_target); then every tool accepts target="name" to inspect the remote, or omits it for local. Password and key auth are both supported; config hot-reloads, no restarts, and switching targets is just conversation.

Tools (17, all read-only)

Tool

What it answers

list_targets

Which inspection targets exist (local + registered remotes/containers)

check_target

Probe a target and return its identity card

add_target / remove_target

Conversational target registration / removal (preview → confirm)

ros_install_info

Is ROS installed on the target? Which distro?

machine_readiness

Is the target machine fit to install/run ROS?

system_overview

One-page snapshot: nodes + topics + wiring

list_nodes / get_node_info

Which nodes run / what a node publishes & subscribes

list_topics / get_topic_info

Which topics exist & their types / endpoint counts and QoS

sample_topic

Topic data (≤30s sampling + content-change detection)

get_topic_rate

Publish rate (≤30s + verdict: stable / intermittent / erratic)

params

A node's parameter list / a parameter's current value

actions

Action list / one action's detail

show_interface

Field definitions of a message/service/action type

health_check

ROS environment health: daemon status + doctor verdict

Safety

Read-only is designed, not promised: four defense layers (only 17 read-only functions exist in the code / verb allowlist + banned-token denylist / parameter format validation that rejects injection / hard timeouts + audit log). No code path for publishing, calling services, setting parameters, or launching nodes exists. Remote commands self-terminate to prevent orphans. Target management has its own four fences: typed parameters, per-field validation, preview-then-confirm, single serializer. Config lives at ~/.config/ros2-inspector/targets.json (override with --targets) and survives upgrades and uninstalls.

License

MIT

Available Tools

13 tools
actionsA

查询 ROS2 动作（action）。

何时用：想看系统里有哪些动作、某个动作被谁提供服务。 action_name 不传=列出全部动作（show_types=True 时附带类型）； 传入=查看该动作详情：动作服务端/客户端数量（原文返回）。 参数 action_name：动作全名，以 / 开头（如 /rotate_absolute）。 失败时返回 error。

Inputs: show_types, action_name.

get_node_infoA

获取指定节点的连接详情：发布/订阅哪些话题、提供/调用哪些服务与动作。

何时用：已知节点名，想看它与系统其他部分的连接关系； 或配合 system_overview 下钻某个可疑节点。 参数 node：节点全名，以 / 开头（如 /talker），大小写敏感。 返回：CLI 原始分节报告（Publishers/Subscribers/Service Servers/Action Servers 等）。失败时返回 error（常见原因：名称拼错、节点刚好退出）。

Inputs: node (required).

get_topic_infoA

获取指定话题的详情：消息类型、发布者数、订阅者数，以及 QoS 配置。

何时用：确认话题类型；排查"发了没人收/收不到"类问题时看双方数量与 QoS。 参数 topic：话题全名，以 / 开头（如 /chatter），大小写敏感； verbose=True 时附带每个端点的 QoS 详情（推荐）。 返回：CLI 原始输出。失败时返回 error（常见：话题不存在）。

Inputs: topic (required), verbose.

get_topic_rateA

限时统计话题发布频率：观察 duration_s 秒后返回平均频率。

何时用：排查"数据不更新/更新太慢"类问题——先看频率是否正常。 参数 topic：话题全名（/ 开头）；duration_s：1~15 秒，默认 5。 返回：average_rate_hz（平均频率，未统计到时为 None）、raw_tail（原始输出尾部）。 note 字段会说明未统计到频率的原因。

Inputs: topic (required), duration_s.

health_checkA

对 ROS2 环境本身做健康检查：daemon 状态 + doctor 体检结论。

何时用：怀疑问题不在业务节点，而在 ROS 环境/网络/daemon 本身时； 或 list_nodes 为空想进一步定位原因。 返回：daemon_running（是否在运行）、doctor_returncode （0 全部通过 / 1 有警告 / 2 有错误）、verdict（doctor 结论行）、 warnings_found（警告摘要）、raw_tail（doctor 原始输出尾部）。 注意：doctor 含网络检查，最长约 30 秒。失败时返回 error 字段。

Inputs: no named parameters.

list_nodesA

列出当前 ROS2 系统中所有正在运行的节点名。

何时用：确认某个节点是否活着；排查前先看看系统里有什么。 返回：node_count 与 nodes 列表（全名以 / 开头）。 nodes 为空说明未发现任何节点——系统未启动、与本机 ROS_DOMAIN_ID 不同或 daemon 异常，可用 health_check 进一步检查。 失败时返回 error 字段。

Inputs: no named parameters.

list_topicsA

列出当前系统中的全部话题及其消息类型。

何时用：想看系统里在传什么数据、某个话题的类型是什么。 返回：topic_count 与 topics 列表（name + type 字段）。 失败时返回 error 字段。

Inputs: no named parameters.

machine_readinessA

评估本机是否适合安装/运行 ROS2。无需安装 ROS 即可运行（纯 Python，零子进程）。

何时用：准备在这台机器上安装 ROS / 部署机器人软件之前的体检。 返回：操作系统与版本、内核、架构、CPU/内存/磁盘概况、网络接口、 主机名解析、locale、ROS_DOMAIN_ID，并对照官方支持矩阵给出参考结论 （verdict 字段）与改进建议（hints 列表）。

Inputs: no named parameters.

paramsA

读取指定节点的参数（只读，不支持设置）。

何时用：想看某节点配置了什么、某个行为开关当前是什么值。 参数 node：节点全名，以 / 开头（如 /talker）； name：参数名（不带前导斜杠，如 use_sim_time；复杂参数名可含 . 与 /）。 name 不传=列出该节点全部参数名；传入=读取该参数当前值 （raw 字段为含类型前缀的原文，如 "Integer value: 10"）。 失败时返回 error（常见：节点名拼错、节点无此参数）。

Inputs: node (required), name.

ros_install_infoA

检测本机是否安装了 ROS2、装了哪些发行版。无需安装 ROS 即可运行。

何时用：不确定这台机器有没有 ROS、装的什么版本、工具能否查看时， 先调这个再决定用哪些查看类工具。 返回：installed（布尔）、distros 列表（发行版名+路径）、PATH 上是否 直接可用 ros2、当前 MCP 工具将使用的发行版、ROS 相关环境变量。

Inputs: no named parameters.

sample_topicA

限时采样话题内容：抓取最多 max_messages 条消息，或 timeout_s 秒到期即停。

何时用：想看某话题里数据实际长什么样、字段值是否合理。 参数 topic：话题全名（/ 开头）；max_messages：150 条，默认 5； timeout_s：115 秒，默认 5。命令一定会在限时内返回，不会挂起。 返回：messages_received（实际条数）、stopped_because （message_limit / timeout / publisher_stopped）、raw（消息原文，未解析）。 采样窗口内无消息时 note 字段会说明（话题可能没有发布者）。

Inputs: topic (required), timeout_s, max_messages.

show_interfaceA

查看 ROS2 消息/服务/动作类型的字段定义。

何时用：拿到一个类型名（如 sample_topic 返回里的 type）想看它有哪些字段、 各字段是什么意思。 参数 interface_type：格式为 包/类型/名称，例如 std_msgs/msg/String、 example_interfaces/srv/AddTwoInts、turtlesim/action/RotateAbsolute。 返回：definition 字段为字段定义原文。失败时返回 error（常见：类型名拼错、 相应功能包未安装）。

Inputs: interface_type (required).

system_overviewA

获取当前 ROS2 系统的一页式快照：节点、话题、连接关系与数量统计。

何时用：回答"系统现在什么状态"类问题的第一入口——先看总览， 发现异常节点/话题后再用 get_node_info / get_topic_info / sample_topic 下钻。 返回：node_count / topic_count 统计、nodes 列表、topics 列表（含类型）、 connections（每个节点的发布/订阅概况）。节点数超过 12 个时只展开前 12 个 （notes 字段会注明）。失败时返回 error 或 notes 说明原因，不会中断会话。

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.2/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target clearly distinct objects (nodes, topics, actions, interfaces), and descriptions explicitly route usage. There is mild overlap between system_overview and list_nodes/list_topics (the former is a superset), and three environment tools (ros_install_info, machine_readiness, health_check) share a diagnostic flavor, but each is scoped differently enough to pick correctly.

    Naming Consistency3/5

    All names are snake_case, which is good, but conventions are mixed: verb_noun (show_interface, list_nodes, get_topic_info, sample_topic), noun-phrase (health_check, machine_readiness, system_overview, ros_install_info), and bare/broad nouns (params, actions). Readable overall but not a predictable single pattern.

    Tool Count5/5

    13 tools is well within the ideal 3-15 range and each tool covers a distinct slice of ROS2 inspection (install, readiness, health, nodes, topics, sampling, rate, params, actions, interfaces). No tool feels redundant or trivial.

    Completeness4/5

    The read-only inspection domain is well covered across environment, topology, topics, sampling, params, and actions. Minor gaps: there is no dedicated service-listing or service-calling tool, and params is read-only, but for an inspector these are acceptable and mostly workable via node/topic tools.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers