ros2-doctor-mcp
# ros2-doctor-mcp
[](https://github.com/darshmenon/ros2_doctor_mcp/actions/workflows/ci.yml)
[](LICENSE)
An MCP server that answers **"why isn't my robot moving?"** for ROS 2. Most ROS MCP servers *control* a robot (publish, call services, send goals). This one only *diagnoses*: it is read-only, never publishes, and never changes anything, so it is safe to point an agent at a running robot.

*The tool results are real output captured through MCP on a UR3 + MoveIt Gazebo sim (healthy, then `arm_controller` deactivated). The question and the agent's reply are illustrative. Source: `docs/demo_raw.txt`, `docs/make_demo_gif.py`.*
It wraps existing read-only doctors and returns one normalised result, `{ok, findings: [{level, code, msg, hint}]}`:
| Tool | Wraps | Answers |
|---|---|---|
| `diagnose_robot` | all of the below | **start here**: detects which stacks are on the domain (Nav2, an arm, MoveIt, SLAM, cameras), runs every doctor that applies in parallel, returns one merged verdict, errors first, each finding tagged with its source |
| `diagnose_nav2` | [nav2_doctor](https://github.com/darshmenon/nav2_doctor) | stale TF, dead odom or scan, inactive Nav2 servers, no `cmd_vel`, flapping goals, no progress |
| `nav2_ready` | `nav2_doctor --ready` | pre-flight: can this stack navigate right now? |
| `diagnose_arm` | [armdoc](https://github.com/darshmenon/armdoc) | inactive controller, silent `/joint_states`, joint at a limit, stalled trajectory, missing `move_group` |
| `arm_ready` | `armdoc --ready` | pre-flight for a ros2_control arm |
| `diagnose_perception` | [percept_doctor](https://github.com/darshmenon/percept_doctor) | cameras, depth and point clouds: dead or stale streams, low rate, dark or frozen images, invalid depth, empty clouds, missing `camera_info` |
| `diagnose_slam` | [slam_doctor](https://github.com/darshmenon/slam_doctor) | SLAM health: map stalls, lost tracking, odometry drift, no loop closures (slam_toolbox, Cartographer, RTAB-Map, ORB-SLAM3) |
| `analyze_force` | [forcetrace](https://github.com/darshmenon/forcetrace) | offline: did a peg-in-hole or press run jam or insert, peak and steady force, time in contact |
| `check_reach` | [reachlens](https://github.com/darshmenon/reachlens) | offline: can a UR3 or UR5e reach this tool-down pose? IK error, manipulability, joint-limit margin |
| `score_map` | [nav_explore_eval](https://github.com/darshmenon/nav_explore_eval) | offline: coverage, wall recall and precision of a saved map against ground truth |
| `ros_graph` | `ros2 node list`, `ros2 topic list -t` | what is visible on a domain; start here when a doctor says nothing is visible |
| `analyze_trajectory` | [trajlens](https://github.com/darshmenon/trajlens) | offline: jerk spikes, limit violations, slow profiles in a recorded trajectory (CSV, JSON, rosbag2); no robot needed |
Every tool takes `ns` (namespace), `seconds` (watch time, clamped to 1 to 120) and `domain_id` (sets `ROS_DOMAIN_ID` for that call only). Each finding carries a `hint` with a suggested next step.
## Install
**Docker** (ROS 2 Humble and the doctors are built in; nothing else to install):
```bash
docker build -t ros2-doctor-mcp https://github.com/darshmenon/ros2_doctor_mcp.git
claude mcp add ros2-doctor -- docker run -i --rm --net=host -e ROS_DOMAIN_ID=0 ros2-doctor-mcp
```
`--net=host` lets the container see robots on this machine; set `ROS_DOMAIN_ID` to match yours (or pass `domain_id` in a tool call). The image uses UDP-only Fast DDS, because shared memory does not work between a container and the host (discovery succeeds but no data arrives).
**From source** (you already have ROS 2):
```bash
# a ROS 2 install with the doctors you want
cd ~/ros2_ws/src && git clone https://github.com/darshmenon/nav2_doctor.git && git clone https://github.com/darshmenon/armdoc.git
cd .. && colcon build --packages-select nav2_doctor armdoc
pip install git+https://github.com/darshmenon/ros2_doctor_mcp.git # or `pip install ros2-doctor-mcp` once it is on PyPI
```
Run the server from a shell where ROS 2 and your workspace are sourced.
## Use with Claude Code
```bash
claude mcp add ros2-doctor -- ros2-doctor-mcp
```
or in `.mcp.json`:
```json
{"mcpServers": {"ros2-doctor": {"command": "ros2-doctor-mcp"}}}
```
Then ask: *"The robot on domain 77 won't move. Why?"* and the agent calls `diagnose_robot`.
## Configuration
The doctors are found on `PATH` (`nav2_doctor`, `armdoc`), else through `ros2 run`. Override either with an environment variable:
```bash
ROS2_DOCTOR_NAV2_CMD="python3 -m nav2_doctor.doctor"
ROS2_DOCTOR_ARM_CMD="ros2 run armdoc armdoc"
```
## Not included
`nav2_fault_inject` and `armchaos` deliberately break a running robot, so they stay out of a read-only server. `ctrlbench` is a long benchmark, not a quick question.
## Safety
- The wrapped doctors only subscribe to topics and query lifecycle or controller state.
- The server runs them as subprocesses with a hard timeout and a clamped watch time. There is no tool that publishes, calls a mutating service, or sends a goal.
- Pairs well with a control-oriented ROS MCP server: let that one move the robot, and use this one to find out why it did not.
## Tests
```bash
pip install ".[test]" && pytest -q
```
The unit tests stub the subprocess, so they need neither ROS nor a robot. The Nav2 and arm tools were also run end to end through the MCP protocol against live Gazebo sims (see the changelog).
## Roadmap
- fault injectors (nav2_fault_inject, armchaos) are deliberately not exposed: this server stays read-only
- merged node logs tied to a finding
- multi-robot: one call per namespace
- the first PyPI release (the package builds and passes `twine check`; publishing waits on a trusted publisher, see `.github/workflows/release.yml`)
License: Apache-2.0.
TDQS
Scored across 12 tools
The core families are clear: diagnose_* tools for deep read-only verdicts, *_ready for boolean pre-flight checks, analyze_*/check_*/score_map for offline post-hoc analysis, and ros_graph for graph introspection. The main soft spot is that diagnose_robot (aggregates all stacks) overlaps with the per-stack diagnose_nav2 / diagnose_arm / diagnose_slam / diagnose_perception, which could cause an agent to hesitate, though "Start here" and "merged verdict" mitigate this. diagnose_nav2 vs nav2_ready and diagnose_arm vs arm_ready are close in topic but differ clearly in output shape (findings vs boolean).
All names use consistent snake_case and mostly follow verb_object (diagnose_*, analyze_*, check_reach, score_map), with a small coherent second family noun_ready (nav2_ready, arm_ready) and one noun_noun outlier (ros_graph). The _ready suffix family is internally predictable, so the deviation reads as intentional rather than sloppy. Minor inconsistency between verb-led and noun-led names keeps it from a 5.
Twelve tools is squarely in the well-scoped range and each has a distinct job: five online stack diagnostics, two readiness checks, one graph lister, and four offline analyzers. Nothing appears redundant enough to cut, and no obvious category is missing a tool that would need to be bolted on later. The split between online and offline concerns is a sensible scoping of the server's purpose.
Coverage across the ROS2 debugging lifecycle is strong: graph/domain discovery (ros_graph), per-stack diagnostics (Nav2, arm, SLAM, perception), pre-flight readiness, and offline evaluation of force, reach, maps and trajectories. Gaps are minor but real: ready checks exist only for Nav2 and the arm (not SLAM/perception), and there is no dedicated TF-tree or log/dmesg inspection tool despite stale TF being a cited failure mode. These are workable around via the diagnose_* hints rather than hard dead ends.