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

Klonen Sie das Repository :

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

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
```

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",
]

UV-Umgebung erstellen :
```
uv venv --python /usr/bin/python3.10
```
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.
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

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

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.

Speichern Sie die Konfiguration und starten Sie Claude neu.

Für Cline (VSCode-Erweiterung)

Öffnen Sie in VSCode die Cline-Erweiterungseinstellungen, indem Sie in der Seitenleiste auf das Cline-Symbol klicken.
Navigieren Sie zum Konfigurationsabschnitt der MCP-Server.

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.

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:

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.
```

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
}

ROS 2-Themen überwachen : Überprüfen Sie die Ausgabe des Themas /cmd_vel :
```
ros2 topic echo /cmd_vel
```

Testen

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.
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.
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

ros2-mcp-server/
├── ros2-mcp-server.py  # Main server script integrating FastMCP and ROS 2
├── pyproject.toml      # Project dependencies and metadata
├── .python-version     # Python version specification
├── .gitignore          # Git ignore file
└── README.md           # This file

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

MIT License

Copyright (c) 2025 kakimochi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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 .

ROS2 MCP Server