ros2-inspector
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.