Skip to main content

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.

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

Metadata

Release files for ros2-inspector-mcp 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ros2-inspector-mcp 0.3.0
File Size Uploaded Provenance Actions
ros2_inspector_mcp-0.3.0.tar.gz 120.4 kB Without provenance Details for ros2_inspector_mcp-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ros2-inspector-mcp 0.3.0
File Interpreter ABI Platform Actions
ros2_inspector_mcp-0.3.0-py3-none-any.whl Python 3 none any Details for ros2_inspector_mcp-0.3.0-py3-none-any.whl

Total release size: 161.0 kB

Release files / ros2_inspector_mcp-0.3.0.tar.gz

Download URL ros2_inspector_mcp-0.3.0.tar.gz
Size 120.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cdf01efcf2247a7f9dc9bf886af215481539c0bd85d36ad74d9bdd4cb4b652ec
BLAKE2b-256 checksum
How to use checksums
9f2f71c73e73b11e461325a18e5f6980fd9e4ad9c24ca53ec49b3c939d56cd24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ros2_inspector_mcp-0.3.0-py3-none-any.whl

Download URL ros2_inspector_mcp-0.3.0-py3-none-any.whl
Size 40.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dd2e1de531e4f43f44efd5fb3e96d1adb89d98d1e62bc42fc7ba426abbfe7990
BLAKE2b-256 checksum
How to use checksums
b21ec27aec02b2b1d56d2dba273b8184c395b92af674bde99ca0914a769e7377
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ros2-inspector-mcp 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page