ros2-doctor-mcp
Provides read-only diagnostic tools for ROS 2 robots and stacks, including merged robot diagnosis, Nav2 readiness, arm/ros2_control checks, perception, SLAM, force/trajectory analysis, reachability checks, map scoring, and ROS graph inspection to help determine why a robot is not moving.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ros2-doctor-mcp My robot on ROS domain 77 won't move — why?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ros2-doctor-mcp
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 |
| 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 |
| stale TF, dead odom or scan, inactive Nav2 servers, no | |
|
| pre-flight: can this stack navigate right now? |
| inactive controller, silent | |
|
| pre-flight for a ros2_control arm |
| cameras, depth and point clouds: dead or stale streams, low rate, dark or frozen images, invalid depth, empty clouds, missing | |
| SLAM health: map stalls, lost tracking, odometry drift, no loop closures (slam_toolbox, Cartographer, RTAB-Map, ORB-SLAM3) | |
| offline: did a peg-in-hole or press run jam or insert, peak and steady force, time in contact | |
| offline: can a UR3 or UR5e reach this tool-down pose? IK error, manipulability, joint-limit margin | |
| offline: coverage, wall recall and precision of a saved map against ground truth | |
|
| what is visible on a domain; start here when a doctor says nothing is visible |
| 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):
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):
# 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 PyPIRun the server from a shell where ROS 2 and your workspace are sourced.
Related MCP server: ros2-inspector
Use with Claude Code
claude mcp add ros2-doctor -- ros2-doctor-mcpor in .mcp.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:
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
pip install ".[test]" && pytest -qThe 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.
Available Tools
12 toolsanalyze_forceA
Offline verdict on a recorded contact-force run (peg-in-hole, press, push; CSV): jammed or not, inserted or not, peak and steady force, time in contact. Needs no robot. cols maps CSV columns, e.g. t=time,f_axial=Fz.
Inputs: path (required), cols.
analyze_trajectoryA
Offline quality check of a recorded joint trajectory (CSV, JSON or rosbag2) with trajlens: jerk spikes, limit violations, slow profiles, gaps. Needs no running robot. urdf adds joint limits.
Inputs: path (required), rate, urdf.
arm_readyB
Pre-flight check for a ros2_control arm: ok only if it can move now.
Inputs: ns, moveit, seconds, domain_id.
check_reachA
Can a UR arm (ur3 or ur5e) reach a tool-down pose at x, y, z metres in the base frame? Returns reachable, the IK error, manipulability and joint-limit margin. Offline, no robot needed (MuJoCo IK via reachlens).
Inputs: x (required), y (required), z (required), arm, +1 more.
diagnose_armA
Watch a ros2_control / MoveIt 2 arm and name why it is not moving (inactive controller, silent joint_states, joint at a limit, stalled trajectory, missing move_group ...). Read-only.
Inputs: ns, moveit, seconds, domain_id.
diagnose_perceptionA
Watch the cameras, depth sensors and point clouds on a running robot and report a dead or stale stream, low rate, dark, blown-out or frozen images, mostly invalid depth, empty clouds and missing camera_info. Read-only. Uses percept_doctor.
Inputs: ns, seconds, domain_id.
diagnose_robotA
Start here. Looks at the ROS graph, detects which stacks are present (Nav2, a ros2_control or MoveIt arm, SLAM, cameras), runs every doctor that applies in parallel and returns one merged verdict, errors first, each finding tagged with its source. Good for mobile manipulators. Read-only.
Inputs: ns, seconds, domain_id.
diagnose_slamB
Watch a running SLAM (slam_toolbox, Cartographer, RTAB-Map, ORB-SLAM3) and report map stalls, lost tracking, odometry drift and missing loop closures. Read-only. Uses slam_doctor.
Inputs: ns, seconds, domain_id.
ros_graphA
List the nodes and topics visible on a ROS domain (read-only). Use it first when a doctor reports that nothing is visible, to find the right domain or namespace.
Inputs: domain_id.
score_mapA
Score a saved occupancy map (map_saver .yaml) against a ground-truth map: coverage, wall recall and precision, false-free area. align=true searches for the best translation first. Offline (nav_explore_eval).
Inputs: map_yaml (required), truth_yaml (required), align.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Read-only server insight: why a Linux server or K8s cluster is slow, failing or changed.
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
Free, read-only ship-readiness check for Replit, Lovable and Bolt apps.
Read-only local AI advice, shared reports and website audits. No PC scan or local actions.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides static analysis of ROS 2 workspaces, enabling inspection of packages, dependencies, interfaces, launch files, and robot descriptions without running ROS 2.72Apache 2.0
- AlicenseAqualityBmaintenanceA read-only MCP server that enables LLMs to inspect and analyze ROS 2 systems through natural language, covering nodes, topics, parameters, actions, rates, QoS, and environment health. It can run without ROS 2 installed and safely surfaces runtime system state for diagnosis.131MIT
- AlicenseAqualityBmaintenanceA read-only MCP server that lets an AI agent inspect a ROS2 graph, its underlying DDS participants, readers, writers and QoS mismatches, and recorded bag files, with twelve typed tools that behave the same against a live robot or built-in mock fixtures. It has no write path at all, so it can never publish to the bus or command a robot.18339 PyPI3MIT
- AlicenseAqualityCmaintenanceA read-only diagnostic server that inspects Linux PTP/Chrony status, PHC hardware-timestamping capabilities, and ROS 2 topic header timestamps to surface clock-domain mismatches, jitter, drift, and alignment problems in robotics systems. It exposes 15 tools and 4 prompts that generate traceable JSON or Markdown reports, running entirely locally over stdio without root access, cloud inference, or any clock modification.15Apache 2.0