Ros MCP

🚀 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. It provides tools for monitoring, debugging, and managing ROS 2 nodes, topics, services, and TF2 frames.

🚀 Quick Start

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.

📦 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 Examples

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

📚 Documentation

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.

🔧 Technical Details

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.