Skip to main content
Glama

ROS 2 MCP Server

A Model Context Protocol (MCP) server for ROS 2 that enables GitHub Copilot and other AI agents to interact with ROS 2 systems. This server provides tools for monitoring, debugging, and managing ROS 2 nodes, topics, services, and TF2 frames.

Quickstart

Add the following to .vscode/mcp.json

{
  "servers": {
    "ros": {
      "command": "npx",
      "args": ["ros-mcp"]
    }
  }
}

Ensure the server is selected in tools for vs code copilot

You're good to go! try "List active ros topics" to test it out.

Features

Node Management

  • list_ros_nodes: List all running ROS 2 nodes with detailed information

  • get_node_connections: View all topics a node publishes to and subscribes from

  • get_node_parameters: List parameters for a specific node

  • set_node_parameter: Modify node parameters at runtime

  • run_ros_node: Launch a ROS 2 node from a package

  • run_ros_launch: Execute a launch file

Topic Monitoring

  • list_ros_topics: List all available topics with optional detailed type information

  • get_topic_info: Get detailed information about a specific topic

  • monitor_topic: Subscribe to a topic and collect messages for a specified duration (observational tool with wait capability)

  • publish_to_topic: Publish messages to a topic

Service Management

  • list_ros_services: List all available services

  • call_service: Call a service with optional parameters

TF2 Frame Monitoring

  • monitor_tf2_frames: Monitor TF2 transform frames and relationships (includes static and dynamic transforms)

System Visualization & Debugging

  • generate_ros_graph: Generate dependency graphs showing connections between nodes and topics (supports both text and Graphviz DOT format)

  • check_ros_system_status: Check overall system health, daemon status, and node/topic/service counts

Related MCP server: Rosbridge MCP Server

Installation

Prerequisites

  • ROS 2 (tested with Humble and later)

  • Node.js 18+

  • npm or yarn

Manual Setup

# Clone or navigate to the repository
cd /path/to/ROS-MCP

# Install dependencies
npm install

# Build the TypeScript
npm run build

WSL might need linking the nvm node to the default node path

sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/node /usr/local/bin/node sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/npm /usr/local/bin/npm

Usage

Running the Server

# Direct execution (recommended for MCP integration)
npm start

# Development with ts-node
npm run dev

With GitHub Copilot

Configure the MCP server in your GitHub Copilot settings:

{
  "servers": {
    "ros": {
      "command": "node",
      "args": ["/path/to/ROS-MCP/build/index.js"]
    }
  }
}

Tool Details

Observational Tools (with Wait Capability)

Some tools are designed to collect data over time, allowing the agent to wait and observe:

  • monitor_topic: Waits for 1-30 seconds, collecting messages from a topic. Supports custom message count limits. Perfect for:

    • Observing sensor data streams

    • Verifying topic publishing patterns

    • Debugging message throughput

  • monitor_tf2_frames: Observes TF2 frame transforms over a specified duration (1-30 seconds)

Tool Examples

Monitor a Topic

Tool: monitor_topic
Parameters:
  - topic_name: "/sensor_msgs/LaserScan"
  - duration_seconds: 5
  - message_count: 10

This collects up to 10 messages from the LaserScan topic over 5 seconds.

Generate Node Graph

Tool: generate_ros_graph
Parameters:
  - output_format: "text" (or "dot" for Graphviz)

Returns a visual representation of how nodes and topics are connected.

Monitor System Health

Tool: check_ros_system_status
Parameters:
  - include_diagnostics: true

Provides comprehensive system status including daemon health, active nodes, and services.

Architecture

The server is built with:

  • @modelcontextprotocol/sdk: MCP framework for agent communication

  • Zod: Type-safe parameter validation

  • Node.js Child Process: Command execution for ROS 2 CLI tools

How It Works

  1. Command Execution: Each tool executes the corresponding ros2 CLI command

  2. Output Parsing: Results are parsed and formatted for agent consumption

  3. Timeout Handling: Observational tools use configurable timeouts to collect data

  4. Error Handling: Commands that fail gracefully return error messages

Designing Tools for Agent Observation

This MCP server follows patterns that work well with AI agents:

  1. Blocking Observational Operations: Tools like monitor_topic block for the specified duration, allowing agents to naturally await results

  2. Bounded Time Windows: All monitoring tools have maximum durations (typically 5-30 seconds) to prevent indefinite waits

  3. Progressive Data Collection: Tools collect data incrementally and return results at the end of the observation window

  4. Clear Output Format: Results are structured text that agents can easily parse and reason about

Example Usage with Copilot

A Copilot agent using this MCP can:

Agent: "What topics are currently being published?"
[Uses: list_ros_topics]

Agent: "Let me observe the /cmd_vel topic for 5 seconds"
[Uses: monitor_topic with topic_name="/cmd_vel", duration_seconds=5]
[Waits 5 seconds for data collection]

Agent: "Here are the velocity commands being sent: [parsed data]"

Agent: "Show me how all nodes are connected"
[Uses: generate_ros_graph with output_format="text"]

Agent: "Let me try publishing a test message to the /cmd_vel topic"
[Uses: publish_to_topic]

Agent: "Let me check if any node is having issues"
[Uses: check_ros_system_status with include_diagnostics=true]

Limitations

  • Some ROS 2 CLI commands require the ROS 2 environment to be properly sourced

  • TF2 monitoring requires the tf2_tools package to be installed

  • The server executes commands in the current environment - ensure ROS 2 is properly installed

  • Long-running operations may timeout; adjust duration parameters as needed

Future Enhancements

  • Integration with ROS 2 bag recording/playback

  • Parameter server monitoring

  • Action client/server interface

  • Live rqt plugin integration

  • Rviz2 data streaming

  • Custom message type parsing

  • CLI

License

MIT

Contributing

Contributions welcome! Please ensure all tools handle errors gracefully and include proper parameter validation.

Available Tools

15 tools
call_serviceC

Call a ROS 2 service with optional parameters

Inputs: service_name (required), request.

check_ros_system_statusB

Check overall ROS 2 system status, daemon, and node health

Inputs: include_diagnostics.

generate_ros_graphB

Generate RQT graph showing connections between nodes and topics

Inputs: output_format.

get_node_connectionsA

Get all topics that a node publishes to and subscribes from

Inputs: node_name (required).

get_node_parametersA

Get parameters for a specific ROS 2 node

Inputs: node_name (required).

get_topic_infoA

Get detailed information about a specific ROS 2 topic including message type

Inputs: topic_name (required).

list_ros_nodesA

List all currently running ROS 2 nodes and their information

Inputs: no named parameters.

list_ros_servicesA

List all available ROS 2 services

Inputs: no named parameters.

list_ros_topicsA

List all ROS 2 topics with their types and publishers/subscribers

Inputs: detailed.

monitor_tf2_framesC

Monitor TF2 transform frames and their relationships

Inputs: duration_seconds.

monitor_topicB

Monitor a ROS 2 topic for a specified duration. Collects messages over time.

Inputs: topic_name (required), message_count, duration_seconds.

publish_to_topicB

Publish a message to a ROS 2 topic

Inputs: message (required), topic_name (required), topic_type.

run_ros_launchB

Launch a ROS 2 package launch file

Inputs: launch_file (required), package_name (required), args.

run_ros_nodeC

Run a ROS 2 node from a package

Inputs: node_type (required), package_name (required), args, node_name.

set_node_parameterB

Set a parameter for a ROS 2 node

Inputs: node_name (required), param_name (required), param_value (required).

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 15 tools

    Disambiguation5/5

    Each tool targets a distinct ROS 2 entity (topic, node, service, parameter, tf2, launch). No two tools perform the same action on the same resource; monitor_topic and get_topic_info differ in whether they collect sample messages or describe topic metadata.

    Naming Consistency5/5

    All tool names use snake_case and follow a clear verb_noun pattern: list_*, get_*, set_*, run_*, monitor_*, publish_to_*, call_*, generate_*. There are no mixed conventions or ambiguous verbs like 'process' or 'do'.

    Tool Count5/5

    15 tools is within the sweet spot for a ROS 2 control surface. Each tool addresses a core need: introspection (list, get, monitor), control (run, publish, call), and configuration (set). The count feels appropriate without being bloated.

    Completeness4/5

    The set covers the main ROS 2 interaction modes: nodes, topics, services, parameters, TF frames, and launch files. A notable gap is the lack of action support or explicit node shutdown, but these are advanced use cases; the core workflows are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers