ROS MCP Server 🧠⇄🤖

1# ROS MCP Server 🧠⇄🤖
2 
3![Static Badge](https://img.shields.io/badge/ROS-Available-green)
4![Static Badge](https://img.shields.io/badge/ROS2-Available-green)
5![Static Badge](https://img.shields.io/badge/License-Apache%202.0-blue)
6![Python](https://img.shields.io/badge/python-3.10%2B-blue)
7![pip](https://img.shields.io/badge/pip-23.0%2B-blue)
8![Dev Container](https://img.shields.io/badge/Dev-Container%20Ready-blue)
9![GitHub Repo stars](https://img.shields.io/github/stars/robotmcp/ros-mcp-server?style=social)
10![GitHub last commit](https://img.shields.io/github/last-commit/robotmcp/ros-mcp-server)
11 
12<!-- mcp-name: io.github.robotmcp/ros-mcp-server -->
13 
14<p align="center">
15  <img src="https://github.com/robotmcp/ros-mcp-server/blob/main/docs/images/framework.png"/>
16</p>
17 
18ROS-MCP-Server connects large language models (such as Claude, GPT, and Gemini) with existing robots giving them bidirectional AI integration.  
19 
20With no changes to existing robot source code, this enables:
21- 🗣 **Commanding the robot in natural language** → instructions are translated into ROS/ROS2 commands.  
22- 👀 **Giving AI full visibility** → subscribe to topics, call services, read sensor data, and monitor robot state in real time.  
23 
24 
25### ✅ Key Benefits  
26 
27- **No robot code changes** → only requires adding the `rosbridge` node.  
28- **True two-way communication** → LLMs can both *control* robots and *observe* everything happening in ROS (sensors, topics, parameters).  
29- **ROS1 & ROS2 support** → works with both versions out of the box.  
30- **MCP-compatible** → integrates with any MCP-enabled LLM (Claude Desktop, Gemini, ChatGPT, and beyond).   
31 
32## 🎥 Examples in Action  
33 
34🖥️ **Example - Controlling the MOCA mobile manipulator in NVIDIA Isaac Sim**  
35Commands are entered into Claude Desktop, which uses the MCP server to directly drive the simulated robot.  
36 
37<p align="center">
38  <img src="https://github.com/robotmcp/ros-mcp-server/blob/main/docs/images/result.gif" />
39</p>  
40 
41---
42🐕 **Example - Controlling Unitree Go with natural language**  ([video](https://youtu.be/RW9_FgfxWzs?si=8bdhpHNYaupzi9q3))  
43The MCP server enables the Claude to interpret images from the robot's cameras, and then command the robot based on human natural language commands. 
44 
45<p align="left">
46  <img src="https://contoro.com/asset/media/demo_go2.gif" />
47</p>  
48 
49---
50🏭 **Example - Debugging an industrial robot** ([Video](https://youtu.be/SrHzC5InJDA))  
51- Connecting to an industrial robot enables the LLM to browse all ROS topics and services to assess the robot state. 
52- With no predefined context, the MCP server enables the LLM to query details about custom topic and service types and their syntax (00:28). 
53- Using only natural language, the operator calls the custom services to test and debug the robot(01:42). 
54 
55<p align="center">
56  <a href="https://contoroinc.sharepoint.com/:v:/s/SandboxNewBusiness/EVh2t2_YG9BEl-Bw-8k6xucBcEv7XebJv1MtqLTIfrQpig?e=deu3YO">
57    <img src="https://github.com/robotmcp/ros-mcp-server/blob/main/docs/images/Contoro_robot.png" width="400" alt="Testing and debugging an industrial robot" />
58  </a>
59</p>
60 
61---
62 
63## ⚙️ Features of the ROS MCP Server  
64 
65- **List topics, services, and message types** → explore everything available in your robot’s ROS environment.  
66- **View type definitions (incl. custom)** → understand the structure of any message.  
67- **Publish/subscribe to topics** → send commands or stream robot data in real time.  
68- **Call services (incl. custom)** → trigger robot functions directly.  
69- **Get/set parameters** → read or adjust robot settings on the fly.  
70- 🔜 **Action support** → upcoming support for ROS Actions.  
71- 🔜 **Permission controls** → manage access for safer deployments.  
72 
73---
74 
75## 🛠 Getting Started  
76 
77The MCP server is version-agnostic (ROS1 or ROS2) and works with any MCP-compatible LLM.  
78 
79<p align="center">
80  <img src="https://github.com/robotmcp/ros-mcp-server/blob/main/docs/images/MCP_topology.png"/>
81</p>  
82 
83### Installation  
84 
85Follow the [installation guide](docs/installation.md) for step-by-step instructions to install, run, and troubleshoot the ROS-MCP server.  
86 
87For developers, we also have instructions for [installation from source](docs/installation-from-source.md). 
88 
89If you prefer not to use desktop LLM apps (such as Claude, ChatGPT, or Gemini), you can use the [robot-mcp-client](https://github.com/robotmcp/robot-mcp-client) to run and interact with the MCP server directly from the terminal. 
90 
91---
92 
93## 📚 More Examples & Tutorials  
94 
95Browse our [examples](examples) to see the server in action.  
96We welcome community PRs with new examples and integrations!  
97 
98---
99 
100## 🤝 Contributing  
101 
102We love contributions of all kinds:  
103- Bug fixes and documentation updates  
104- New features (e.g., Action support, permissions)  
105- Additional examples and tutorials  
106 
107Check out the [contributing guidelines](docs/contributing.md) and see issues tagged **good first issue** to get started.  
108 
109---
110 
111## 📜 License  
112 
113This project is licensed under the [Apache License 2.0](LICENSE).  
114