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.1

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.1
File Size Uploaded Provenance Actions
ros2_inspector_mcp-0.3.1.tar.gz 121.7 kB Without provenance Details for ros2_inspector_mcp-0.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 163.0 kB

Release files / ros2_inspector_mcp-0.3.1.tar.gz

Download URL ros2_inspector_mcp-0.3.1.tar.gz
Size 121.7 kB
Tags Source
SHA-256 checksum
How to use checksums
dfb8c6117031d70f4b23521b882a148915f82165f97bb5cc0c69eb64eaa504f8
BLAKE2b-256 checksum
How to use checksums
487684a2dbb10f2a8dacb05de0fbe8a8e88737446f4c38472c64cb2feb0f4ceb
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.1-py3-none-any.whl

Download URL ros2_inspector_mcp-0.3.1-py3-none-any.whl
Size 41.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
302eb636ff78845981e37620cdeca00550b61c0d41621bce8fdbfb9451c355f8
BLAKE2b-256 checksum
How to use checksums
6209f2bc64a0f283de1b48dd812d5602c3c8ae270fa66ddeb0dd5268f91b7d0d
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.1

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