rosbridge-mcp

rosbridge-mcp ist ein Model Context Protocol-Server, der KI-Agenten (Claude Desktop, Cursor, VS Code und jeden anderen MCP-Client) mit Robotern verbindet, die ROS 2 ausführen – über das standardmäßige rosbridge v2-Protokoll (WebSocket + JSON). Sie starten rosbridge_server auf Ihrem Roboter oder ROS-Rechner; dieser MCP-Server verbindet sich über das Netzwerk damit und stellt 11 Tools bereit, mit denen die KI Topics beobachten, den ROS-Graphen und den TF-Baum inspizieren, durch die Kamera des Roboters sehen, Nachrichten veröffentlichen, Dienste aufrufen und ROS 2-Aktionen steuern kann – ohne dass auf dem Rechner des KI-Clients eine ROS-Installation erforderlich ist.

Architektur

+--------------------+   stdio (MCP)   +----------------+   WebSocket/JSON   +------------------+   DDS   +---------+
|  AI client         | <-------------> | rosbridge-mcp  | <----------------> | rosbridge_server | <-----> |  ROS 2  |
|  (Claude, Cursor,  |                 |  (this server) |    rosbridge v2    |  (on the robot)  |         |  graph  |
|   VS Code, ...)    |                 |                |      protocol      |                  |         |         |
+--------------------+                 +----------------+                    +------------------+         +---------+

Related MCP server: ROS2 MCP Server

Schnellstart (60 Sekunden)

pip install git+https://github.com/hieutachi/rosbridge-mcp.git

Oder, sobald veröffentlicht: pip install rosbridge-mcp (PyPI – kommt bald).

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu (siehe die client-spezifischen Anleitungen unten für die genauen Dateipfade):

{
  "mcpServers": {
    "rosbridge": {
      "command": "rosbridge-mcp",
      "env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
    }
  }
}

Fragen Sie dann Ihren Agenten: "Welche Topics hat der Roboter?"

Wählen Sie Ihren Weg

Wählen Sie die Anleitung, die zu Ihnen passt – jede ist in sich abgeschlossen, Sie müssen nicht den Rest dieser README zuerst lesen:

Tools

Insgesamt 11 Tools. Alle Tools geben JSON zurück. Nachrichten- und Argument-Payloads verwenden dieselbe JSON-Darstellung von ROS-Nachrichten, die auch rosbridge verwendet (Feldnamen entsprechen den .msg/.srv/.action-Definitionen).

list_topics

Listet alle Topics mit ihren Nachrichtentypen auf. Keine Parameter.

{"topics": [
  {"name": "/chatter", "type": "std_msgs/msg/String"},
  {"name": "/cmd_vel", "type": "geometry_msgs/msg/Twist"},
  {"name": "/scan",    "type": "sensor_msgs/msg/LaserScan"}
]}

list_nodes

Listet alle laufenden Nodes auf. Keine Parameter.

{"nodes": ["/talker", "/listener", "/rosapi"]}

list_services

Listet alle verfügbaren Dienste auf. Keine Parameter.

{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}

get_topic_snapshot

Abonniert ein Topic, sammelt Nachrichten, kündigt das Abonnement. Parameter: topic (erforderlich), count (Standard 1), timeout Sekunden (Standard 5.0), msg_type (optional, wird normalerweise von rosbridge automatisch erkannt).

Eingabe: {"topic": "/chatter", "count": 2, "timeout": 3.0}

{"topic": "/chatter", "requested": 2, "received": 2,
 "messages": [{"data": "Hello World: 41"}, {"data": "Hello World: 42"}],
 "timed_out": false}

Wenn das Topic still ist, ist received kleiner als requested und timed_out ist true – das Tool hängt nie länger als timeout.

publish_message (verändernd)

Macht ein Topic bekannt und veröffentlicht eine JSON-Nachricht. Parameter: topic, msg_type (vollständiger ROS 2-Typ, z. B. geometry_msgs/msg/Twist), message (JSON-Objekt, das dem Typ entspricht).

Eingabe:

{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist",
 "message": {"linear": {"x": 0.1, "y": 0.0, "z": 0.0},
             "angular": {"x": 0.0, "y": 0.0, "z": 0.2}}}

Ausgabe: {"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}

call_service (verändernd)

Ruft einen beliebigen ROS-Dienst auf. Parameter: service (erforderlich), args (JSON-Objekt, Standard {}), timeout Sekunden (Standard 10.0).

Eingabe: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}

{"service": "/rosapi/topic_type", "success": true,
 "values": {"type": "sensor_msgs/msg/LaserScan"}}

Bei Fehlschlag gibt das Tool {"success": false, "error": "..."} zurück, anstatt eine Ausnahme auszulösen.

send_action_goal (verändernd)

Sendet ein Ziel an einen ROS 2-Aktionsserver (Navigation, Armbewegung, ...). Parameter: action_name, action_type (vollständiger Typ mit /action/, z. B. nav2_msgs/action/NavigateToPose), goal (JSON-Objekt, Standard {}), timeout Sekunden (Standard 30, begrenzt auf ≤ 120), wait_for_result (Standard true).

Eingabe: {"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}}

{"action": "/fibonacci", "goal_id": "send_action_goal:7", "success": true,
 "status": 4, "status_text": "succeeded",
 "values": {"sequence": [0, 1, 1, 2, 3, 5]},
 "last_feedback": {"partial_sequence": [0, 1, 1, 2, 3]}}

Mit wait_for_result: false gibt das Tool sofort {"goal_id": ..., "result_pending": true} zurück – übergeben Sie diese goal_id an cancel_action_goal, um das Ziel später zu stoppen. Erfordert eine rosbridge_suite-Version mit ROS 2-Aktionsunterstützung; bei einer älteren rosbridge gibt das Tool einen Fehler zurück, der ein Upgrade empfiehlt, anstatt zu hängen.

cancel_action_goal (verändernd)

Bricht ein zuvor gesendetes Aktionsziel ab. Parameter: action_name, goal_id (von send_action_goal).

Ausgabe: {"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}

get_tf_tree

Erfasst den TF-Baum (Koordinatentransformation) des Roboters, indem kurz /tf und /tf_static abgehört werden. Parameter: timeout Sekunden (Standard 2.0, begrenzt auf ≤ 10).

{"frame_count": 3,
 "frames": {
   "base_link": {"parent": "odom", "translation": {"x": 1.0, "y": 0.0, "z": 0.0},
                  "rotation": {"x": 0, "y": 0, "z": 0, "w": 1}, "source": "dynamic"},
   "laser":     {"parent": "base_link", "...": "...", "source": "static"}},
 "tree": {"odom": ["base_link"], "base_link": ["laser"]},
 "roots": ["odom"]}

get_camera_image

Nimmt ein Einzelbild von einem Kameratopic als base64 auf, damit visionsfähige Modelle sehen können, was der Roboter sieht. Parameter: topic (bevorzugen Sie ein sensor_msgs/msg/CompressedImage-Topic, z. B. /camera/image_raw/compressed), timeout Sekunden (Standard 5.0, begrenzt auf ≤ 30).

Ausgabe: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (rohe Image-Topics geben zusätzlich width/height/encoding zurück). Bilder über 4 MB werden nicht zurückgegeben – das Tool antwortet mit Metadaten plus einem Fehler, der ein komprimiertes Topic vorschlägt.

get_connection_status

Meldet Verbindungsstatus und Nur-Lese-Modus. Keine Parameter.

{"url": "ws://localhost:9090", "connected": true,
 "connected_since_unix": 1786903978.1, "active_subscriptions": [],
 "pending_service_calls": 0, "readonly": false}

Beispielunterhaltung

Sie: Was sieht der Roboter gerade?

Agent: (ruft list_topics auf, findet /scan vom Typ sensor_msgs/msg/LaserScan, ruft dann get_topic_snapshot mit {"topic": "/scan", "count": 1} auf) Der Laserscanner meldet 360 Entfernungswerte. Das nächste Hindernis ist etwa 0,4 m entfernt bei ungefähr 90° links; der Raum direkt voraus ist für mindestens 2,5 m frei.

Sie: OK, fahren Sie langsam ein Stück vorwärts.

Agent: (ruft publish_message mit {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}} auf) Ein Vorwärtsgeschwindigkeitsbefehl von 0,1 m/s wurde veröffentlicht. Sagen Sie mir, wann ich anhalten soll, und ich veröffentliche Nullgeschwindigkeit.

Für Vision & verkörperte KI

Zwei der schreibgeschützten Tools existieren speziell, um Vision-Sprachmodelle in der physischen Realität des Roboters zu verankern:

• get_camera_image gibt ein echtes Kamerabild als base64 zurück – ein visionsfähiges Modell (Claude, GPT-4o oder ein VLA-Policy-Frontend) kann buchstäblich durch die Kamera des Roboters schauen, bevor es entscheidet, was zu tun ist.

• get_tf_tree gibt dem Modell das räumliche Skelett des Roboters – welche Koordinatensysteme existieren (map, odom, base_link, camera, gripper) und wie sie relativ zueinander positioniert sind.

In Kombination mit get_topic_snapshot (Lidar, Odometrie, Gelenkzustände) und send_action_goal (Navigation, Manipulation) deckt dies den beobachten → überlegen → handeln-Zyklus ab, den Vision-und-Action-Agenten benötigen – über ein einfaches WebSocket, ohne ROS-Installation auf der Modellseite. Beide Wahrnehmungstools funktionieren im Nur-Lese-Modus, sodass Sie einen „schauen, aber nicht anfassen“-Agenten sicher ausführen können.

Konfiguration

Sicherheit

Einem Sprachmodell zu erlauben, /cmd_vel auf einem physischen Roboter zu veröffentlichen, ist ein echtes Risiko. Setzen Sie ROSBRIDGE_MCP_READONLY=true, um im Nur-Lese-Modus zu laufen: publish_message, send_action_goal und cancel_action_goal werden abgelehnt, und call_service erlaubt nur eine feste Whitelist bekannter schreibgeschützter /rosapi-Introspektionsdienste (topics, nodes, services, types, get_param, get_time, ...) – alles, was nicht auf der Liste steht, einschließlich unbekannter zukünftiger /rosapi-Dienste, wird abgelehnt. Die schreibgeschützten Wahrnehmungstools (get_topic_snapshot, get_tf_tree, get_camera_image) funktionieren weiterhin. Wir empfehlen dringend, bei echter Hardware im Nur-Lese-Modus zu starten – siehe die vollständige Sicherheitscheckliste für echte Roboter und das Sicherheitsmodell für den Einsatz in SECURITY.md.

Datenschutz & Rechtliches

Kein Telemetrie, keine Datenerfassung. Geprüft (2026-08): Die einzige Netzwerkverbindung, die dieses Paket jemals öffnet, ist das WebSocket zu der von Ihnen konfigurierten ROSBRIDGE_URL – es gibt keine Analysen, kein Telefonieren nach Hause, keine Absturzberichte, keine versteckten HTTP-Aufrufe, und der Code enthält keine Protokollierung von Nachrichteninhalten auf die Festplatte. Der mitgelieferte Mock-Server bindet nur an 127.0.0.1. Von den Tools zurückgegebene Roboterdaten gehen ausschließlich an Ihren MCP-Client (der sie an das von Ihnen gewählte LLM weiterleitet – dieser Teil liegt in Ihrer Kontrolle, nicht in unserer).

Lizenz-Compliance. Alle Laufzeit- und transitiven Abhängigkeiten haben Lizenzen, die mit der MIT-Lizenz dieses Projekts kompatibel sind – direkt: fastmcp (Apache-2.0), websockets (BSD-3-Clause); wichtige transitive: mcp (MIT), pydantic (MIT), starlette (BSD-3-Clause), httpx (BSD-3-Clause), anyio (MIT), cryptography (Apache-2.0/BSD-3). Eine transitive Abhängigkeit, certifi, ist MPL-2.0 – ein Datei-Level-Copyleft, das nur für Änderungen an certifis eigenen Dateien gilt und mit MIT-Nutzung und -Weiterverbreitung kompatibel ist. Kein GPL/AGPL/proprietärer Code irgendwo im Abhängigkeitsbaum, und der gesamte Code in diesem Repository ist Originalarbeit, die für dieses Projekt geschrieben wurde.

FAQ

Muss ich ROS auf dem Rechner installiert haben, auf dem der KI-Client läuft? Nein. Nur Python 3.10+. ROS und rosbridge laufen auf dem Roboter (oder in Docker, oder in einem Simulator); dieser Server kommuniziert mit ihnen über WebSocket.

Funktioniert es mit ROS 1? Das rosbridge v2-Protokoll ist dasselbe, daher funktionieren grundlegende Operationen auch gegen einen ROS 1 rosbridge_server – verwenden Sie ROS 1-Typnamen (std_msgs/String). Nur ROS 2 wird in CI getestet.

Der Agent meldet, dass keine Verbindung hergestellt werden kann. Überprüfen Sie, dass rosbridge läuft (ros2 launch rosbridge_server rosbridge_websocket_launch.xml), dass ROSBRIDGE_URL auf den richtigen Host/Port verweist und dass Port 9090 erreichbar ist (Firewall). Jede Anleitung in docs/ hat einen Abschnitt zur Fehlerbehebung.

Kann ich es ohne Roboter oder Simulator ausprobieren? Ja — python -m rosbridge_mcp.mock_server 9090 startet einen simulierten rosbridge mit vordefinierten Topics; setzen Sie dann ROSBRIDGE_URL auf ws://localhost:9090.

Werden meine Daten irgendwohin gesendet? Der Server verbindet sich nur mit der von Ihnen konfigurierten ROSBRIDGE_URL. Topic-Daten werden an Ihren MCP-Client zurückgegeben, der sie an das von Ihnen verwendete LLM weiterleitet — behandeln Sie Sensordaten entsprechend.

Fahrplan

Gestaffelter Plan mit Zielen, Ergebnissen und benötigten Ressourcen pro Phase: siehe ROADMAP.md. Highlights: v0.2 Action-Client + TF + Kamerabilder (in v0.2.0 umgesetzt), v0.3 HTTP-Transport + Docker-Image + rosbridge-Authentifizierung/TLS, v0.4 Multi-Roboter-Flotten + MCP-Ressourcen (URDF/Karte), v1.0 stabile API + offizieller MCP-Registry-Eintrag + Gazebo/Isaac Sim-Beispiele.

Dieses Projekt unterstützen

rosbridge-mcp wird von einer Person in Teilzeit in einer frühen Phase entwickelt und gepflegt. Was existiert, ist echt und getestet: 11 Tools für Topics, Dienste, ROS 2-Aktionen, TF und Kamerabilder; 43 automatisierte Tests, die bei jedem Commit in CI laufen; szenarienbasierte Dokumentation für 5 Benutzerpfade; einen schreibgeschützten Sicherheitsmodus mit einer Dienst-Whitelist; und eine geprüfte, telemetriefreie Codebasis.

Was der Fahrplan braucht, um Wirklichkeit zu werden, ehrlich gesagt:

• v0.3 (Bereitstellung und Sicherheit): Teilzeit-Entwicklungswochen, eine kleine Cloud-VM oder ein selbstgehosteter Runner für Docker-Image-Builds und — am wichtigsten — ein sicherheitsbewusster Prüfer für die rosbridge-Authentifizierungs-/TLS-Ebene.

• v0.4 (Flotten): Zugang zu 2+ gleichzeitig laufenden Robotern oder Simulatorinstanzen und Design-Feedback von einem echten Robotiklabor (Suche nach einem akademischen oder industriellen Pilotpartner).

• v1.0 (Stabilität und Ökosystem): Kontinuierliche Maintainer-Zeit (~2 Tage/Woche für ein Quartal), ein RTX-Klasse GPU-Workstation für Isaac Sim-Validierung — die größte Hardware-Anforderung des gesamten Fahrplans — und optional ein kostengünstiger Roboter (~1.000–3.000 $) für Hardware-in-the-Loop-CI.

Wie Sie helfen können, in aufsteigendem Aufwand:

1. Star das Repo — Sichtbarkeit hilft einem frühen Projekt, Mitwirkende zu gewinnen.

2. Testen Sie es mit Ihrem Roboter oder Simulator und eröffnen Sie ein Issue mit Ihrer ROS-Distribution + rosbridge-Version — Kompatibilitätsberichte sind der günstigste Weg, dies robust zu machen.

3. Reichen Sie einen PR ein — docs/development.md erklärt die Codebasis in 10 Minuten, und jedes Fahrplanelement ist beanspruchbar.

4. Sponsor oder Partner — wenn Ihr Labor oder Unternehmen Simulatorzeit, Hardware, eine GPU-Workstation oder finanzierte Entwicklungszeit anbieten kann, kontaktieren Sie mich über github.com/hieutachi.

Verwandte Ressourcen

Wenn Sie sich mit Robotik beschäftigen, ist das Robotics RL & UAV ebook eine begleitende Lernressource des Autors, die Reinforcement Learning und UAV-Robotik abdeckt.

Mitwirken

Beiträge sind willkommen! Siehe CONTRIBUTING.md und den Entwicklungsleitfaden. Bitte unterschreiben Sie Ihre Commits (DCO).

Lizenz

MIT — siehe LICENSE. Abhängigkeitslizenzen sind freizügig und kompatibel: fastmcp (Apache-2.0), websockets (BSD-3-Clause). Keine GPL/AGPL-Abhängigkeiten.

Tóm tắt tiếng Việt

rosbridge-mcp là một MCP server cầu nối giữa AI agent (Claude Desktop, Cursor, VS Code...) và robot chạy ROS 2 thông qua giao thức rosbridge (WebSocket + JSON). Không cần cài ROS trên máy chạy AI client.

Tài liệu được chia theo từng kịch bản — chọn đúng hướng dẫn cho bạn trong thư mục docs/:

• Dùng Claude Desktop — cấu hình JSON từng bước trên Windows/macOS/Linux

• Dùng Cursor / VS Code — cấu hình mcp.json trong editor

• Chưa có robot — chạy thử với Docker (ros:humble + rosbridge) hoặc TurtleBot3/Gazebo, hoặc mock server đi kèm

• Có robot thật — checklist an toàn: bật ROSBRIDGE_MCP_READONLY=true trước, đọc /odom, /scan để hiểu robot rồi mới mở quyền publish /cmd_vel

• Developer — kiến trúc code, cách thêm tool mới, chạy test với mock (không cần ROS)

11 tool: list_topics, list_nodes, list_services, get_topic_snapshot, publish_message, call_service, send_action_goal, cancel_action_goal, get_tf_tree, get_camera_image, get_connection_status. Bật ROSBRIDGE_MCP_READONLY=true để chặn mọi thao tác ghi (publish, action) khi làm việc với robot thật — các tool đọc (TF, camera, topic) vẫn hoạt động bình thường.

Tài liệu học kèm theo của tác giả: Robotics RL & UAV ebook — ebook về học tăng cường (reinforcement learning) và robot UAV.