Skip to main content
Glama

ros2-doctor-mcp

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

diagnose_robot on a UR3 with MoveIt: healthy, then the arm controller deactivated

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

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

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

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

SLAM health: map stalls, lost tracking, odometry drift, no loop closures (slam_toolbox, Cartographer, RTAB-Map, ORB-SLAM3)

analyze_force

forcetrace

offline: did a peg-in-hole or press run jam or insert, peak and steady force, time in contact

check_reach

reachlens

offline: can a UR3 or UR5e reach this tool-down pose? IK error, manipulability, joint-limit margin

score_map

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

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 PyPI

Run 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-mcp

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

Available Tools

12 tools
analyze_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_nav2A

Watch a running Nav2 stack and name why the robot is not moving (stale TF, dead odom/scan, inactive lifecycle nodes, no cmd_vel, flapping goals ...). Read-only. Returns ok and findings with hints.

Inputs: ns, 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

    A3.7/5.0

    Scored across 12 tools

    Disambiguation4/5

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

    Naming Consistency4/5

    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.

    Tool Count5/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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      13
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      18
      339 PyPI
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      15
      Apache 2.0