ROS 2 MCP Server

How to use

You will interact with the ROS MCP server through an MCP client or through Copilot-style tooling. Start by configuring a local MCP client to connect to the ROS MCP server, then use the available tools to inspect nodes, topics, services, and TF2 frames. Practical tasks include listing active nodes, observing topic traffic over a short window, calling services, or generating a graph of how nodes and topics are connected.

Typical workflows you can perform: - List current ROS 2 nodes and their details - Inspect which topics a node publishes or subscribes to - Retrieve or modify a node’s parameters at runtime - Launch a node or a launch file from a package - Monitor topics or TF2 frames for a defined duration - Publish test messages to a topic to validate communication - Generate a dependency graph showing node and topic relationships - Check overall ROS 2 system health and counts of nodes, topics, and services.

How to install

Prerequisites you need before installing the ROS MCP server:
- ROS 2 (tested with Humble and later)
- Node.js 18+ 
- npm or yarn

Step 1: Install dependencies and build the server
```bash
# Navigate to the server directory
cd /path/to/ROS-MCP

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Step 2: Run the server locally (stdio) or prepare for Copilot integration
- Direct execution (recommended for MCP integration):
```bash
npm start
```
- Development with ts-node:
```bash
npm run dev
```

If you prefer referencing a built script from a specific path, you can configure Copilot to launch the built entrypoint as shown in the integration snippet.

Step 3: Optional Copilot configuration example
```json
{
  "servers": {
    "ros": {
      "command": "node",
      "args": ["/path/to/ROS-MCP/build/index.js"]
    }
  }
}

Additional sections

Tooling and usage details are provided below to help you leverage the full capabilities of the ROS MCP server. You can connect via an MCP client and call the functions listed under Tools to manage and observe your ROS 2 system.

Supported tools are grouped by capability and include node management, topic monitoring, service management, TF2 frame monitoring, and system visualization. Each tool returns structured results that you can parse to make informed decisions about your ROS 2 network.

Example usage with Copilot

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]"

Troubleshooting and notes

Some ROS 2 CLI commands require the ROS 2 environment to be properly sourced. TF2 monitoring may require the tf2_tools package to be installed. The server executes commands in the current environment, so ensure ROS 2 is properly installed and sourced in your shell or execution environment. Long-running operations may timeout; adjust duration parameters as needed.

Architecture and how it works

The server is built with a MCP framework that facilitates agent communication, a type-safe parameter validation layer, and a Node.js runtime for executing ROS 2 CLI tools. Commands are executed, results are parsed, and errors are handled gracefully to provide clear feedback to the agent.

Tools overview

The ROS MCP server exposes a range of tools for different tasks: - Node Management: list_ros_nodes, get_node_connections, get_node_parameters, set_node_parameter, run_ros_node, run_ros_launch - Topic Monitoring: list_ros_topics, get_topic_info, monitor_topic, publish_to_topic - Service Management: list_ros_services, call_service - TF2 Frame Monitoring: monitor_tf2_frames - System Visualization & Debugging: generate_ros_graph, check_ros_system_status

Metadata

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.

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.

list_ros_services

List all available services.

call_service

Call a service with optional parameters.

monitor_tf2_frames

Monitor TF2 transform frames and relationships (static and dynamic transforms).

generate_ros_graph

Generate dependency graphs showing connections between nodes and topics (text or Graphviz DOT format).

check_ros_system_status

Check overall system health, daemon status, and node/topic/service counts.