ros2-mcp-server

<div align="center">

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=0:0d1117,50:00d4ff,100:0055ff&height=220&section=header&text=ros2-mcp-server&fontSize=52&fontColor=ffffff&fontAlignY=45&desc=Universal%201000%2B%20AI%20Model%20Gateway%20%26%20Physical%20Robotics%20Coprocessor&descSize=18&descAlignY=68&descColor=c9d1d9&animation=fadeIn" />

<br/>

The World's First Universal Physical AI Coprocessor & MCP Gateway for ROS2

Connect 1,000+ AI Models (Claude, GPT-4o, Gemini 2.0, DeepSeek R1, Llama 3) to Real Robots & Gazebo Simulations with 3-Tier Execution Sandboxing and Fast-Forward Kinematic Trajectory Prediction.

<br/>

<div align="center"> <img width="850" src="docs/assets/demo.gif" alt="Claude tuning PID values on a live robot" /> <br/><i>Watch Claude instantly tune a robot's PID controller in real-time via ros2-mcp-server.</i> </div> <br/>

📖 Overview · ⚡ Quick Start · 🌐 1000+ AI Matrix · 🌟 World-First Features · 🛠️ Tools · 🔒 Safety · 💬 Community

</div>

---

🌐 Supported AI Clients & Frameworks

<p align="center"> <img src="https://img.shields.io/badge/Claude_Desktop-000000?style=for-the-badge&logo=anthropic&logoColor=white"/> <img src="https://img.shields.io/badge/Cursor_IDE-0055FF?style=for-the-badge&logo=cursor&logoColor=white"/> <img src="https://img.shields.io/badge/Windsurf-00D4FF?style=for-the-badge&logo=windsurf&logoColor=black"/> <img src="https://img.shields.io/badge/Antigravity_IDE-7A00FF?style=for-the-badge&logo=google&logoColor=white"/> <img src="https://img.shields.io/badge/Roo_Code-181717?style=for-the-badge&logo=github&logoColor=white"/> <img src="https://img.shields.io/badge/OpenAI_SDK-412991?style=for-the-badge&logo=openai&logoColor=white"/> <img src="https://img.shields.io/badge/LangChain-121011?style=for-the-badge&logo=python&logoColor=white"/> <img src="https://img.shields.io/badge/LlamaIndex-00A67E?style=for-the-badge&logo=meta&logoColor=white"/> </p>

---

🧠 What This Solves

Robotics engineers face a massive friction point when integrating AI models into physical workflows:

"I want to ask Claude or GPT-4o why my quadcopter is oscillating — but copy-pasting 10,000 lines of ROS2 topic sensor dumps into a chat window is tedious and dangerous."

ros2-mcp-server solves this permanently. It creates a high-throughput, bidirectional bridge between any MCP-compatible AI agent and a ROS2 DDS network:

• 📡 Live Sensor Introspection: Stream telemetry from /scan, /imu/data, /battery_state, /odom
• 🔮 Pre-Execution Kinematic Simulation: Simulate $(x,y,\theta)$ trajectories in <0.1ms compute before actuation
• 🛡️ Predictive Neural Safety: Auto-correct excessive velocity or negative PID gains with mathematical proof
• 🗺️ Spatial ASCII Radar Visualizer: Render 360° LiDAR pointclouds into text-based 2D spatial maps
• 🐝 Multi-Robot Swarm Orchestration: Intercept and manage /drone_1, /rover_2, /arm_3 in one session
• 🎛️ Sandboxed Control: Tune controller PID parameters and publish velocity commands safely

---

🌟 World-First Unimagined Innovations

1. 🔮 Kinematic Trajectory Predictor (predict_trajectory)

Runs a 1000Hz fast-forward kinematic physics simulation (<0.1ms compute) before any motion command reaches hardware. Predicts $(x, y, \theta)$ position trajectories, dynamic stability margins, and obstacle risk in virtual time.

2. 🛡️ Predictive Neural Safety Guard (predictive_safety_check)

Evaluates proposed parameter or velocity commands against motor torque limits. If an LLM proposes an unstable input (e.g. negative PID gains), the server automatically caps the values to safe physics bounds and feeds the mathematical proof back to the AI.

3. 🗺️ Spatial ASCII Radar Map (get_spatial_map)

Converts raw 360° LaserScan pointclouds into a 2D ASCII spatial map directly in MCP response JSON, allowing text & vision LLMs to "see" surrounding space:

+------------------+  [R] = Robot Center (0,0)
|      .  *  .     |  [*] = Detected Obstacle Point
|   .    [R]   .   |  [.] = Clear Navigable Space
|      .     .     |
+------------------+  Heading: 0.0 rad | Clear Path: RIGHT

4. 🐝 Multi-Robot Swarm Fleet Orchestrator (swarm_fleet_status)

Aggregates and coordinates multi-namespace ROS2 fleets (/drone_1, /rover_2, /arm_3) within a single unified MCP session.

---

⚡ Quick Start (60 Seconds)

1. Frictionless 1-Line Installer

curl -sSL https://raw.githubusercontent.com/EngineerAbdullahBinZafar/ros2-mcp-server/main/install.sh | bash

2. System Diagnostic Check (doctor)

Run our CLI diagnostic doctor to verify Python runtime, rclpy status, and client config files:

ros2-mcp-server doctor

3. Instant Simulation Playground

No physical robot nearby? Spin up our built-in virtual robot:

ros2-mcp-server --demo-sim

---

🛠️ Available MCP Tools (16 Tools)

Tool Name	Innovation / Function	Category
ping	Test bridge latency & active node count	System
system_diagnostics	Full health check (battery, LiDAR, IMU, issues)	Health
list_topics	List active ROS2 topics & message types	Graph
read_topic	Read message from topic (latched support)	Data
publish_topic	Sandboxed message publisher	Actuation
get_robot_snapshot	Parallel fetch of LiDAR + IMU + Battery + Odom	Parallel
list_nodes	Enumerate active nodes & namespaces	Graph
get_node_info	Inspect node publishers, subscribers & services	Graph
get_parameter	Read live parameters from running node	Params
set_parameter	Sandboxed parameter update	Params
get_pid_state	Read Kp, Ki, Kd gains & stability bounds	Control
tune_pid	Apply new PID gains with engineering advice	Control
🔮 predict_trajectory	[WORLD-FIRST] Kinematic pre-simulation of trajectory ($x,y,\theta$)	Innovation
🛡️ predictive_safety_check	[WORLD-FIRST] Risk evaluation & auto-correction of LLM inputs	Innovation
🗺️ get_spatial_map	[WORLD-FIRST] Renders 360° LiDAR into 2D ASCII radar grid	Innovation
🐝 swarm_fleet_status	[WORLD-FIRST] Multi-namespace ROS2 swarm fleet manager	Innovation

---

🔒 3-Tier Execution Sandbox

Level	Set Via	Operational Envelope
read_only	SAFETY_LEVEL=read_only	AI can only read telemetry — zero hardware writes
safe_write	SAFETY_LEVEL=safe_write (default)	Writes restricted to explicit topic/param allowlist
full	SAFETY_LEVEL=full	Unrestricted write access — use in simulation only

Every decision is logged in a thread-safe, timestamped audit log:

print(sandbox.get_audit_log())

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│           AI Client (Claude / Cursor / GPT-4o)              │
└──────────────────────────────┬──────────────────────────────┘
                               │  MCP stdio / JSON-RPC 2.0
┌──────────────────────────────▼──────────────────────────────┐
│                    ros2-mcp-server v1.2.0                   │
│                                                             │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │ O(1) Tool Dispatcher    │     │  CommandSandbox       │  │
│  │ (16 Tools <0.08ms)      │     │  (3-Tier Safety)      │  │
│  └────────────┬────────────┘     └───────────┬───────────┘  │
│               │                              │              │
│  ┌────────────▼──────────────────────────────▼───────────┐  │
│  │        ROS2 Interface Layer (Native / Simulation)    │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────┘
                               │  DDS / Serial / WebSocket
┌──────────────────────────────▼──────────────────────────────┐
│                    ROS2 Robot System                        │
│         (Gazebo Sim / TurtleBot / Nav2 / STM32)             │
└─────────────────────────────────────────────────────────────┘

---

📊 Performance Benchmarks

• Tool Dispatch Overhead: < 0.08 ms ($O(1)$ compiled lookup table)
• Kinematic Simulation: < 0.10 ms (1000Hz fast-forward compute)
• Memory Footprint: ~14.2 MB RAM
• Test Coverage: 42 / 42 Tests Passed (Simulation mode)

---

🧪 Running Tests

git clone https://github.com/EngineerAbdullahBinZafar/ros2-mcp-server
cd ros2-mcp-server

python run_tests.py

---

📖 Extended Documentation

• 🌐 Client Integration Setup (15+ Clients)
• ⚡ Performance & Latency Benchmarks
• 🌟 World-First Feature Architecture
• 🔒 Security & Threat Model Policy
• 🏗️ System Architecture Deep Dive
• 🤝 Contribution Guide

---

👨‍💻 Author

Abdullah Bin Zafar — Mechatronics & Control Engineering, UET Lahore
Building robots that think, act, and reason safely.

---

💬 Community & Support

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• ⭐ Star the repository to support open-source AI robotics!