ros-mcp
Provides tools for monitoring, debugging, and managing ROS 2 nodes, topics, services, and TF2 frames, enabling AI agents to interact with ROS 2 systems.
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., "@ros-mcp list all ros topics"
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.
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 buildWSL 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 devWith 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: 10This 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: trueProvides 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
Command Execution: Each tool executes the corresponding
ros2CLI commandOutput Parsing: Results are parsed and formatted for agent consumption
Timeout Handling: Observational tools use configurable timeouts to collect data
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:
Blocking Observational Operations: Tools like
monitor_topicblock for the specified duration, allowing agents to naturally await resultsBounded Time Windows: All monitoring tools have maximum durations (typically 5-30 seconds) to prevent indefinite waits
Progressive Data Collection: Tools collect data incrementally and return results at the end of the observation window
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_toolspackage to be installedThe 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 toolscall_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
Scored across 15 tools
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.
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'.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Python-based server that enables AI assistants to control robots by integrating the Model Context Protocol (MCP) with ROS 2, allowing for natural language commands that translate into robot movement via the /cmd\_vel topic.84-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides tools to publish messages to ROS topics via rosbridge WebSocket, enabling integration between language models and ROS-based robotics systems.MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for ROS 2, enabling AI assistants to introspect and interact with ROS 2 systems.26 PyPI2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for AI agents to inspect and control ROS2 graphs, enabling topic listing, node info, service calls, parameter management, and pub/echo without manual ROS2 CLI usage.12MIT