ros2_mcp: Multifunctional Server for Simplifying AI-ROS2 Integration with Standard MCP Protocol

Ros2 MCP

The MCP server for ROS2 enables AI tools to connect to ROS2 nodes, topics, and services through the standard MCP protocol. It provides functions such as topic subscription and publishing, service calls, and action control, supports nested fields and automatic type discovery, and simplifies the integrated development of AI and ROS2.

Developer tools Artificial intelligence chatbots #ROS2 Integration #AI Assistant #Robot Control #Development Tool .Python

rating : 2.5 points

downloads : 11.6K

update time : 2025-12-12

Open Site

What is the ROS2 MCP Server?

The ROS2 MCP Server is an intelligent bridge that connects AI assistants (such as GitHub Copilot, Claude Desktop) with the ROS2 robot operating system. It allows you to directly interact with the robot through a chat interface: view sensor data, control robot actions, call services, and debug problems, as simple as having a conversation with a robot expert.

How to use the ROS2 MCP Server?

Simply configure the server in your AI tools (VS Code Copilot, Claude Desktop, etc.), and then you can ask questions in natural language. For example: 'List all current ROS2 topics', 'Subscribe to the camera topic and analyze the images', 'Move the robot to a specified position'. The server will automatically convert your requests into ROS2 commands and return the results.

Applicable Scenarios

Robot development and debugging, sensor data analysis, teaching demonstrations, rapid prototype verification, system monitoring, multi - robot collaboration testing, etc. It is particularly suitable for scenarios where you need to quickly interact with the ROS2 system but don't want to memorize complex commands.

Main Features

Topic Management

View all available topics, subscribe to topics to collect messages, publish messages to topics, and analyze topic data statistical information. Supports complex nested message structures.

Service Call

List all available services and directly call ROS2 services and pass parameters. Automatically discover service types and request fields.

Action Control

Send action goals, wait for results, cancel actions, subscribe to feedback and status updates. Fully supports the ROS2 Action protocol.

Intelligent Prompt Words

Built - in predefined prompt word templates, such as topic health checks, data relaying, difference monitoring, etc., to perform complex analysis tasks with one click.

Historical Data Query

Retrieve historical messages from the data black box (a storage system similar to ROS bag), supporting time range filtering.

Automatic Type Discovery

Dynamically discover all message and service types and their field definitions, so that the AI assistant always knows what data can be manipulated.

Docker Support

Provides pre - built Docker images for one - click deployment without configuring a complex environment.

QoS Automatic Selection

Automatically select the best quality - of - service settings for topics and services to ensure optimal communication performance.

Advantages

⚡ Quick configuration in 1 minute, the simplest ROS2 MCP server setup in the world

🤖 AI - assisted debugging, let AI help troubleshoot ROS2 problems in real - time

📊 Intelligent data analysis, query robot sensor data in natural language

🚀 Greatly improve productivity, control robots, analyze logs, and debug problems through chat

💡 No need for professional ROS2 knowledge, AI automatically translates requests into correct ROS2 commands

0️⃣ Zero - friction setup, use stdio for transmission without a proxy or web server

🔧 Automatic QoS selection to ensure the best communication performance

🐋 Full Docker support for rapid deployment

Limitations

Requires a basic ROS2 environment (ROS2 Humble/Jazzy installed)

Custom message types need to source the corresponding package first

Control scenarios with extremely high real - time requirements may not be suitable (there is network latency)

Requires AI clients to support the MCP protocol (such as VS Code Copilot, Claude Desktop)

How to Use

Install the ROS2 Environment

Ensure that the ROS2 Humble or Jazzy version is installed and the workspace is set up.

Configure the AI Client

Configure the MCP server in your AI tools. The configuration methods vary for different clients.

Start the ROS2 Node

Start the ROS2 nodes you want to interact with, such as robot control nodes and sensor nodes.

Start Conversing with the AI

In the AI chat interface, make requests in natural language, such as viewing topics and calling services.

Usage Examples

Drone Mission Planning

Control drones to execute complex mission sequences through natural language instructions, such as taking off, cruising, taking pictures, and returning to base.

Sensor Data Analysis

Analyze robot sensor data in real - time to detect anomalies or extract statistical information.

System Health Check

Quickly diagnose the state of the ROS2 system and check if topics and services are working properly.

Multi - Topic Data Comparison

Compare the differences between raw sensor data and processed data.

Frequently Asked Questions

Do I need to install ROS2 to use this server?

Which AI clients are supported?

Can it handle custom message types?

What about the real - time performance? Is it suitable for controlling robots?

How to debug server problems?

Are there any demos or tutorials?

Does it support ROS1?

How to contribute code or report issues?

Related Resources

GitHub Repository

Project source code, issue tracking, contribution guidelines

Discord Community

Communicate with other users, get help, and share use cases

MCP Protocol Specification

Official specification document of the Model Context Protocol

Installation Guide

Detailed installation and configuration steps, supporting multiple AI clients

Drone Demo Tutorial

Experience the complete drone control demo in the Gazebo simulation

Docker Image

Pre - built Docker image for rapid deployment

ROS2 Official Website

Official ROS2 documentation and tutorials

Guide to Creating Custom Prompt Words

Learn how to create your own AI prompt word templates

🚀 ROS2 MCP Server

A Python implementation of the Model Context Protocol (MCP) for ROS 2, enabling AI tooling to connect with ROS 2 nodes, topics, and services.

This is a Python implementation of the Model Context Protocol (MCP) for ROS 2. The server allows AI tooling to connect with ROS 2 nodes, topics, and services using the MCP standard over stdio. It is designed to be the easiest ROS 2 MCP server to configure.

✨ Features

List available topics
List available services
List available actions with their types and request fields
Call services
Subscribe to topics to collect messages
Publish messages to topics
Echo messages on topics
Get fields from message types
Send an action goal and optionally wait for the result
Request the result of an action goal
Subscribe to feedback messages from an action
Subscribe to status updates of an action
Cancel a specific goal or all active goals
Get messages from WiseVision Data Black Box (InfluxDB alternative to Rosbag2)

📦 Installation

Follow the installation guide for step-by-step instructions:

🧩 Install in Visual Studio Code Copilot
🤖 Install in Claude Desktop
💻 Install in Warp
🐳 Build Docker Image locally

💻 Usage Examples

📊 Available Prompts

📘 Want to create a custom prompt? Check the guide here

base.ros2-topic-echo-and-analyze

Subscribe to a ROS2 topic, collect messages for a specified duration, and provide statistical analysis of the collected data.

➡️ Can auto-detect topic if only one is available. Analyzes message rates, counts, and statistics on numeric fields.

🔄 base.ros2-topic-relay

Subscribe to one ROS2 topic and republish messages to another topic with optional transformations.

➡️ Supports identity relay, rate limiting, and change-based filtering.

🏥 base.ros2-node-health-check

Check if expected ROS2 topics and services are available and functioning correctly with optional publication rate monitoring.

➡️ Provides comprehensive health report with status indicators and recommendations.

🔍 base.ros2-topic-diff-monitor

Compare two ROS2 topics and report differences in their messages with detailed field-by-field analysis.

➡️ Useful for comparing raw sensor data with filtered/processed versions or verifying topic synchronization.

ROS2 MCP has Prompts extension with additional prompts See here

💡 Don’t know what prompts are? See the MCP spec here.

🚀 Drone Mission Using Prompts

🌍 Real-world examples:

📚 Documentation

🎯 Why Choose This MCP Server?

Save hours of development time with native AI integration for your ROS 2 projects:

Why this ROS 2 MCP server ⭐

⚡ 1-minute setup - World's easiest ROS 2 MCP configuration
0️⃣ Zero-friction setup - stdio transport, no brokers, no webserver.
🔌 Auto type discovery - a built-in “list interfaces” tool dynamically enumerates available topics and services together with their message/service definitions (fields, types, schema) — so the client always knows exactly what data can be published or called.
✨ Nested field support: Handle complex message structures with ease.
🤖 AI-powered debugging - Let AI help you troubleshoot ROS 2 issues in real time
📊 Smart data analysis - Query your robot's sensor data using natural language
🚀 Boost productivity - Control robots, analyze logs, and debug issues through AI chat
💡 No ROS 2 expertise required - AI translates your requests into proper ROS 2 commands
🐋 Dockerized: Ready-to-use Docker image for quick deployment.
🔧 Auto QoS selection: Automatically selects appropriate Quality of Service settings for topics and services, ensuring optimal communication performance without manual configuration.

Perfect for: Robotics developers, researchers, students, and anyone working with ROS 2 who wants to leverage AI for faster development and debugging.

If you find this useful, please ⭐ star the repo — it helps others discover it.

🚀 Enjoying this project?
Feel free to contribute or reach out for support! Write issues, submit PRs, or join our Discord community to connect with other ROS 2 and AI enthusiasts.

🔧 ROS 2 Tools

📋 Topics

Tool	Description	Inputs	Outputs
`ros2_topic_list`	Returns list of available topics	–	`topic_name` (string): Topic name `topic_type` (string): Message type
`ros2_topic_subscribe`	Subscribes to a ROS 2 topic and collects messages for a duration or message limit	`topic_name` (string) `duration` (float) `message_limit` (int) (defaults: first msg, 5s)	`messages` `count` `duration`
`ros2_get_messages`	Retrieves past messages from a topic (data black box)	`topic_name` (string) `message_type` (string) `number_of_messages` (int) `time_start` (str) `time_end` (str)	`timestamps` `messages`
`ros2_get_message_fields`	Gets field names and types for a message type	`message_type` (string)	Field names + types
`ros2_topic_publish`	Publishes message to a topic	`topic_name` (string) `message_type` (string) `data` (dict)	`status`

🛠 Services

Tool	Description	Inputs	Outputs
`ros2_service_list`	Returns list of available services	–	`service_name` (string) `service_type` (string) `request_fields` (array)
`ros2_service_call`	Calls a ROS 2 service	`service_name` (string) `service_type` (string) `fields` (array) `force_call` (bool, default: false)	`result` (string) `error` (string, if any)

🎯 Actions

Tool	Description	Inputs	Outputs
`ros2_list_actions`	Returns list of available ROS 2 actions with their types and request fields	–	`actions[]` (array) └ `name` (string) └ `types[]` (array of string) └ `request_fields` (array)
`ros2_send_action_goal`	Sends a goal to an action. Optionally waits for the result.	`action_name` (string) `action_type` (string) `goal_fields` (object) `wait_for_result` (bool, default: false) `timeout_sec` (number, default: 60.0)	`accepted` (bool) `goal_id` (string\|null) `send_goal_stamp` (object\|null) `waited` (bool) `result_timeout_sec` (number\|null) `status_code` (int\|null) `status` (string\|null) `result` (object\|null) \| `error` (string)
`ros2_cancel_action_goal`	Cancels a specific goal or all goals for an action	`action_name` (string) `goal_id_hex` (string, required if `cancel_all`=false) `cancel_all` (bool, default: false) `stamp_sec` (int, default: 0) `stamp_nanosec` (int, default: 0) `wait_timeout_sec` (number, default: 3.0)	`service` (string) `return_code` (int) `return_code_text` (string) `goals_canceling[]` (array of {`goal_id`, `stamp`}) \| `error` (string)
`ros2_action_request_result`	Waits for the RESULT of a given goal via GetResult	`action_name` (string) `action_type` (string) `goal_id_hex` (string, 32-char UUID) `timeout_sec` (number\|null, default: 60.0) `wait_for_service_sec` (number, default: 3.0)	`service` (string) `goal_id` (string) `waited` (bool) `result_timeout_sec` (number\|null) `status_code` (int\|null) `status` (string\|null) `result` (object\|null) \| `error` (string)
`ros2_action_subscribe_feedback`	Subscribes to feedback messages for an action. Can filter by goal_id. Collects messages for duration or max count.	`action_name` (string) `action_type` (string) `goal_id_hex` (string\|null) `duration_sec` (number, default: 5.0) `max_messages` (int, default: 100)	`topic` (string) `action_type` (string) `goal_id_filter` (string\|null) `duration_sec` (number) `messages[]` (array of {`goal_id`, `feedback`, `recv_stamp`}) \| `error` (string)
`ros2_action_subscribe_status`	Subscribes to an action's status topic and returns collected status frames	`action_name` (string) `duration_sec` (number, default: 5.0) `max_messages` (int, default: 100)	`topic` (string) `duration_sec` (number) `frames[]` (array of {`stamp`, `statuses[]`}) \| `error` (string)

🔧 Technical Details

🐞 Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/ros2_mcp run mcp_ros_2_server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

📚 Origins and evolution

We built this server to make AI‑assisted ROS 2 development fast and reliable. Internally, we needed a simple way for agents to discover message types, publish/subscribe to topics, and call services—without boilerplate or flaky networking. That led to a few core design goals:

Handle all ROS 2 message types (including nested fields) so agents can write and test any code
Integrate topic pub/sub and service calls to validate behavior end‑to‑end
Work seamlessly with GitHub Copilot in VS Code and other MCP clients
Use a simple stdio transport to avoid network complexity

After dogfooding it, we open‑sourced the project to help the broader ROS 2 community build faster with AI. It’s now useful not only for development, but also for controlling robots, running QoS experiments, and analyzing live data and robot/swarm state. The project is actively maintained—features and improvements ship regularly based on user feedback. If this project helps you, please star the repo and share your use case!