ros2-mcp-server

ros2-mcp-server ist ein Python-basierter Server, der das Model Context Protocol (MCP) mit ROS 2 integriert und es KI-Assistenten ermöglicht, Roboter über ROS 2-Themen zu steuern. Er verarbeitet Befehle über FastMCP und läuft als ROS 2-Knoten. Er veröffentlicht geometry_msgs/Twist -Nachrichten an das Thema /cmd_vel , um die Roboterbewegung zu steuern.

Diese Implementierung unterstützt Befehle wie „5 Sekunden lang mit 0,2 m/s vorwärts bewegen und anhalten“ mit dem /cmd_vel Publisher mit dem Namen pub_cmd_vel .

Merkmale

• MCP-Integration : Verwendet FastMCP, um Befehle von MCP-Clients (z. B. Claude) zu verarbeiten.

• ROS 2 Native : Funktioniert als ROS 2-Knoten und veröffentlicht direkt an /cmd_vel .

• Zeitbasierte Steuerung : Unterstützt zeitbasierte Bewegungsbefehle (z. B. für eine bestimmte Zeit bewegen und anhalten).

• Asynchrone Verarbeitung : Kombiniert asyncio von FastMCP mit der Ereignisschleife von ROS 2 für einen effizienten Betrieb.

Related MCP server: MCP Terminal

Voraussetzungen

• ROS 2 : Bescheidene Distribution installiert und bezogen.

• Python : Version 3.10 (erforderlich für die Kompatibilität mit ROS 2 Humble).

• uv : Python-Paketmanager für die Abhängigkeitsverwaltung.

• Abhängigkeiten :

  • rclpy : ROS 2 Python-Clientbibliothek (mit ROS 2 installiert).

  • fastmcp : FastMCP-Framework für die MCP-Serverimplementierung.

  • numpy : Für ROS 2 Nachrichtentypen erforderlich.

Installation

1. Klonen Sie das Repository :

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

2. Python-Versionskonfiguration : Dieses Projekt verwendet Python 3.10, wie von ROS 2 Humble gefordert. Die Datei .python-version ist bereits konfiguriert:

   # .python-version content 3.10

3. Projektabhängigkeiten : Die Datei pyproject.toml ist mit den erforderlichen Abhängigkeiten konfiguriert:

   # pyproject.toml content [project] name = "ros2-mcp-server" version = "0.1.0" description = "ROS 2 MCP Server" readme = "README.md" requires-python = ">=3.10" dependencies = [ "fastmcp", "numpy", ]

4. UV-Umgebung erstellen :

   uv venv --python /usr/bin/python3.10

5. Aktivieren Sie die virtuelle Umgebung :

   source .venv/bin/activate

   Am Anfang Ihrer Eingabeaufforderung wird (.venv) angezeigt, was darauf hinweist, dass die virtuelle Umgebung aktiv ist.

6. Abhängigkeiten installieren :

   uv pip install -e .

MCP-Serverkonfiguration

Um diesen Server mit Claude oder anderen MCP-Clients zu verwenden, müssen Sie ihn als MCP-Server konfigurieren. So richten Sie ihn ein:

Für Claude Desktop

1. Öffnen Sie die Claude Desktop-Einstellungen und navigieren Sie zum Abschnitt MCP-Server.

2. Fügen Sie einen neuen MCP-Server mit der folgenden Konfiguration hinzu:

   "ros2-mcp-server": { "autoApprove": [], "disabled": false, "timeout": 60, "command": "uv", "args": [ "--directory", "/path/to/ros2-mcp-server", "run", "bash", "-c", "export ROS_LOG_DIR=/tmp && source /opt/ros/humble/setup.bash && python3 /path/to/ros2-mcp-server/ros2-mcp-server.py" ], "transportType": "stdio" }

   Wichtig : Ersetzen Sie /path/to/ros2-mcp-server durch den tatsächlichen Pfad zu Ihrem Repository. Wenn Sie das Repository beispielsweise nach /home/user/projects/ros2-mcp-server geklont haben, verwenden Sie stattdessen diesen Pfad.

3. Speichern Sie die Konfiguration und starten Sie Claude neu.

Für Cline (VSCode-Erweiterung)

1. Öffnen Sie in VSCode die Cline-Erweiterungseinstellungen, indem Sie in der Seitenleiste auf das Cline-Symbol klicken.

2. Navigieren Sie zum Konfigurationsabschnitt der MCP-Server.

3. Fügen Sie einen neuen MCP-Server mit der folgenden Konfiguration hinzu:

   "ros2-mcp-server": { "autoApprove": [], "disabled": false, "timeout": 60, "command": "uv", "args": [ "--directory", "/path/to/ros2-mcp-server", "run", "bash", "-c", "export ROS_LOG_DIR=/tmp && source /opt/ros/humble/setup.bash && python3 /path/to/ros2-mcp-server/ros2-mcp-server.py" ], "transportType": "stdio" }

   Wichtig : Ersetzen Sie /path/to/ros2-mcp-server durch den tatsächlichen Pfad zu Ihrem Repository, wie im Beispiel von Claude Desktop.

4. Sie können den Server sofort ein- und ausschalten und die Verbindung direkt über die Cline MCP-Einstellungsschnittstelle überprüfen, ohne VSCode neu starten oder die Erweiterung neu laden zu müssen.

Verwendung

Sobald der MCP-Server konfiguriert ist, können Sie mit Claude Befehle an den Roboter senden:

1. Beispielbefehl : Bitten Sie Claude, den Roboter 5 Sekunden lang mit 0,2 m/s vorwärts zu bewegen:

   Please make the robot move forward at 0.2 m/s for 5 seconds.

2. Direkte Tool-Verwendung : Sie können das Tool move_robot auch direkt verwenden:

   { "linear": [0.2, 0.0, 0.0], "angular": [0.0, 0.0, 0.0], "duration": 5.0 }

3. ROS 2-Themen überwachen : Überprüfen Sie die Ausgabe des Themas /cmd_vel :

   ros2 topic echo /cmd_vel

Testen

1. Mit einem Simulator :

   • Starten Sie einen ROS 2-kompatiblen Simulator (z. B. Gazebo mit TurtleBot3):

     export TURTLEBOT3_MODEL=burger ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py

   • Verwenden Sie Claude, um Bewegungsbefehle zu senden.

   • Beobachten Sie, wie sich der Roboter im Gazebo bewegt.

2. Mit einem echten Roboter :

   • Stellen Sie sicher, dass Ihr Roboter richtig eingerichtet ist, um das Thema /cmd_vel zu abonnieren.

   • Verwenden Sie Claude, um Bewegungsbefehle zu senden.

   • Der Roboter sollte sich gemäß den Befehlen bewegen.

3. Erwartete Ausgabe :

   • Der Server protokolliert Bewegungsbefehle und Stoppbefehle.

   • Claude erhält eine Antwort wie: "Successfully moved for 5.0 seconds and stopped" .

Fehlerbehebung

• ROS 2-Protokollierungsfehler : Wenn beim Protokollieren des Verzeichnisses Fehler auftreten, stellen Sie sicher, dass die Umgebungsvariable ROS_LOG_DIR auf ein beschreibbares Verzeichnis (z. B. /tmp ) eingestellt ist.

• Nicht übereinstimmende Python-Version : Stellen Sie sicher, dass Sie Python 3.10 verwenden, da ROS 2 Humble für diese Version erstellt wurde.

• Verbindungsfehler : Wenn Claude den Fehler „Verbindung geschlossen“ meldet, überprüfen Sie, ob die MCP-Serverkonfiguration korrekt ist und alle Abhängigkeiten installiert sind.

Verzeichnisstruktur

Einschränkungen

• Einzelnes Thema : Unterstützt derzeit /cmd_vel mit Twist -Nachrichten. Erweitern Sie ros2-mcp-server.py für andere Themen oder Dienste.

• Grundlegende Befehle : Unterstützt derzeit einfache Bewegungsbefehle. Komplexere Verhaltensweisen erfordern eine zusätzliche Implementierung.

Lizenz

Beachten Sie, dass dieses Projekt FastMCP verwendet, das unter der Apache-Lizenz 2.0 lizenziert ist. Die Bedingungen dieser Lizenz gelten auch für die Verwendung von FastMCP-Komponenten.

Danksagung

• Erstellt mit FastMCP und ROS 2 .