coppeliasim-mcp

Ein MCP-Server, mit dem Claude Code (oder jeder MCP-Client) eine laufende CoppeliaSim-4.10-Simulation steuern kann: Szenen aufbauen, Objekte bewegen, Gelenke und Näherungssensoren erstellen, die Simulation ausführen und Sensoren wieder auslesen.

Er setzt bewusst keine beliebige Lua-Ausführung aus. Das ist der Hauptunterschied zu anderen CoppeliaSim-MCP-Servern. Siehe Sicherheit.

Tool-Namen sind standardmäßig spanisch, mit optionalen englischen und portugiesischen Aliasen – siehe Tool-Namenssprachen.

Nicht verbunden mit, unterstützt von oder gepflegt von Coppelia Robotics AG. CoppeliaSim ist eine Marke von Coppelia Robotics AG. Dies ist eine unabhängige Drittanbieter-Integration; für den Simulator selbst besuchen Sie coppeliarobotics.com.

Anforderungen

• CoppeliaSim 4.10 läuft, mit dem ZMQ-Remote-API-Add-on aktiv. Es ist standardmäßig aktiviert und lauscht auf Port 23000.

• Python 3.10 oder neuer.

Related MCP server: Robonine MCP Server

Installation

# Recommended: no clone, no virtualenv to manage
uvx coppeliasim-mcp

# Or install it
pip install coppeliasim-mcp

Registrieren Sie es bei Claude Code:

claude mcp add coppelia -- uvx coppeliasim-mcp

Oder, für jeden MCP-Client, der eine JSON-Konfiguration liest:

{
  "mcpServers": {
    "coppelia": {
      "command": "uvx",
      "args": ["coppeliasim-mcp"]
    }
  }
}

Konfiguration

Alle Einstellungen sind optionale Umgebungsvariablen. Sie können auch in einer .env-Datei im Arbeitsverzeichnis liegen – siehe .env.example.

Tools

Simulationssteuerung – iniciar_simulacion, detener_simulacion, pausar_simulacion, estado_simulacion, tiempo_simulacion

Szenen – cargar_escena, cerrar_escena

Objekte – listar_objetos, obtener_posicion, fijar_posicion, obtener_orientacion, fijar_orientacion, crear_primitiva, eliminar_objeto, emparentar_objeto, fijar_detectable

Gelenke – obtener_posicion_junta, fijar_objetivo_junta, fijar_velocidad_junta, obtener_fuerza_junta

Näherungssensoren – crear_sensor_proximidad, leer_sensor_proximidad, comprobar_sensor_proximidad

Tool-Namensprachen

Tools sind auf Spanisch definiert (crear_primitiva, leer_sensor_proximidad, …). Mit COPPELIA_IDIOMAS werden Aliase in Englisch und Portugiesisch registriert, die auf dieselben Funktionen zeigen – keine doppelte Logik, nur mehr Namen im Katalog.

Der Katalog wird bei jeder Anfrage an das Modell gesendet, daher sind Aliase standardmäßig deaktiviert. Wissenswert, bevor du sie aktivierst: Das Modell braucht keine übersetzten Namen, um dich in einer anderen Sprache zu verstehen. Tool-Namen sind Bezeichner, kein Benutzertext – bitte um „move the cube forward“ oder „mova o cubo para frente“ und es greift trotzdem zu fijar_posicion. Aliase helfen, wenn du den Katalog auf einen Blick lesen willst oder ein Tool explizit in einem Prompt benennen möchtest.

Beispiele

examples/carrito_diferencial.py baut einen vollständigen Roboter mit Differenzialantrieb und Hindernisvermeidung und misst, ob er tatsächlich funktioniert. Siehe examples/README.md.

Sicherheit

Die Lua-Umgebung von CoppeliaSim hat Zugriff auf os und io. Ein Tool, das beliebiges Lua ausführt, verwandelt daher jede Prompt-Injection – zum Beispiel Text in einer .ttt-Szene von Drittanbietern, die das Modell untersuchen soll – in eine Befehlsausführung auf deinem Rechner. Dieser Server hat kein solches Tool, bewusst.

Die restliche Oberfläche ist bewusst schmal gehalten:

• cargar_escena löst den Pfad (Path.resolve(strict=True)) bevor er ihn mit COPPELIA_DIRECTORIO_ESCENAS vergleicht, sodass ../.. und Symlinks nicht entkommen können, und er akzeptiert nur Szenen-Erweiterungen.

• COPPELIA_MODO_LECTURA=1 deaktiviert alle verändernden Tools auf einmal.

• Das Szenenverzeichnis ist standardmäßig das Arbeitsverzeichnis, nicht dein Home-Verzeichnis.

Hinweise, die Debugging-Zeit sparen

Dinge über die CoppeliaSim-API, die leicht falsch gemacht werden können und die die Tools direkt sichtbar machen:

• leer_sensor_proximidad erkennt nicht. Es gibt das Ergebnis des letzten Sensor-Durchgangs des Simulators zurück, also meldet es bei gestoppter Simulation immer nichts. Verwende comprobar_sensor_proximidad, um bei Bedarf zu erkennen.

• Ein Objekt muss als erkennbar markiert sein, um von einem Näherungssensor gesehen zu werden. Dafür ist fijar_detectable da, und es ist der übliche Grund, warum ein Sensor „nicht funktioniert“.

• Ein breiter Kegel, der horizontal zeigt, sieht den Boden, bevor er dein Hindernis sieht. Mit halber Öffnung a und Sensor in Höhe h tritt der Boden bei h / tan(a) in den Kegel ein. Wenn das unter der Sensorreichweite liegt, meldet der Sensor den Boden.

• Umbenennen von Geschwisternummern. Nach dem Aufhängen von /Cylinder[1] an einem Chassis kann /Cylinder[3] zu /Cylinder[1] werden. Liste die Objekte zwischen aufeinanderfolgenden emparentar_objeto-Aufrufen erneut auf, oder löse die Handles im Voraus auf.

• Elternschaft verbindet zwei dynamische Formen nicht starr. Nicht-statische Formen fallen, wenn sie nicht durch ein Gelenk oder einen Kraftsensor eingeschränkt sind.

Veröffentlichung

Die Veröffentlichung läuft bei einem Tag-Push über .github/workflows/publicar.yml:

# bump version in pyproject.toml first, then
git tag v0.1.0 && git push --tags

Der Workflow weigert sich zu veröffentlichen, wenn Tag und Version in pyproject.toml nicht übereinstimmen, installiert das gebaute Wheel auf Python 3.10 und 3.13 und führt scripts/prueba_humo.py aus – einen MCP-Handshake plus eine Prüfung, dass ein Aufruf ohne Simulator antwortet statt zu hängen – bevor er etwas hochlädt. Eine PyPI-Version kann nie überschrieben oder wiederverwendet werden, also ist ein Fehlschlag in CI viel billiger als eine Versionsnummer zu verbrennen.

Er authentifiziert sich bei PyPI über Trusted Publishing (OIDC), sodass kein Token in den Repository-Secrets gespeichert ist.

Lizenz

MIT – siehe LICENSE.

Die MIT-Lizenz deckt nur diesen Server ab. CoppeliaSim selbst wird separat von Coppelia Robotics AG lizenziert, und dieses Paket enthält keinen Teil davon und redistributiert keinen Teil davon – es spricht mit einem Simulator, den du selbst installierst und lizenzierst.

coppeliasim-mcp (español)

Un servidor MCP para manejar una simulación de CoppeliaSim 4.10 desde Claude Code o cualquier cliente MCP: construir escenas, mover objetos, crear juntas y sensores de proximidad, correr la simulación y leer los sensores.

No expone ejecución de Lua arbitrario, a propósito. Es la diferencia principal con los otros MCP de CoppeliaSim que circulan. El Lua de CoppeliaSim tiene acceso a os e io, así que una tool de ese tipo convierte cualquier prompt injection —por ejemplo, texto dentro de una escena .ttt de terceros— en ejecución de comandos sobre tu máquina.

Sin afiliación, respaldo ni mantenimiento por parte de Coppelia Robotics AG. CoppeliaSim es una marca de Coppelia Robotics AG. Esto es una integración independiente de terceros; para el simulador, ve a coppeliarobotics.com.

Requisitos

• CoppeliaSim 4.10 abierto, con el add-on ZMQ remote API activo. Viene habilitado por defecto, escuchando en el puerto 23000.

• Python 3.10 o superior.

Instalación

uvx coppeliasim-mcp                              # recomendado
pip install coppeliasim-mcp                      # o instalado
claude mcp add coppelia -- uvx coppeliasim-mcp   # registrar en Claude Code

Configuración

Variables de entorno, todas opcionales. También se pueden poner en un .env en el directorio de trabajo — mira .env.example.

Idiomas de los nombres de tools

Las tools se definen en español. COPPELIA_IDIOMAS registra alias en inglés y portugués sobre las mismas funciones: no duplica lógica, solo añade nombres.

El catálogo viaja en cada petición al modelo, así que los alias vienen apagados. Y conviene saber esto antes de encenderlos: el modelo no necesita los nombres traducidos para entenderte en otro idioma. Los nombres de tools son identificadores, no texto de cara al usuario — pídele "move the cube forward" o "mova o cubo para frente" y usará fijar_posicion igual. Los alias sirven para leer el catálogo de un vistazo, o para nombrar una tool explícitamente.

Ejemplos

examples/carrito_diferencial.py construye un carrito de tracción diferencial completo con evasión de obstáculos, y mide si de verdad funciona. Mira examples/README.md.

Cosas que ahorran horas de depuración

• leer_sensor_proximidad no detecta. Devuelve el resultado del último barrido del simulador, así que con la simulación detenida siempre dice que no hay nada. Para detectar en el momento, comprobar_sensor_proximidad.

• Un objeto tiene que estar marcado como detectable para que un sensor de proximidad lo vea. Para eso está fijar_detectable, y es la causa habitual de un sensor que "no funciona".

• Un cono ancho en horizontal ve el suelo antes que el obstáculo. Con media apertura a y el sensor a altura h, el suelo entra en el cono a h / tan(a). Si eso queda por debajo del alcance, el sensor reporta el piso.

• Emparentar renumera las rutas de los hermanos. Al colgar /Cylinder[1] de un chasis, /Cylinder[3] puede pasar a ser /Cylinder[1]. Vuelve a listar los objetos entre llamadas, o resuelve los handles antes de tocar la jerarquía.

• Emparentar no une rígidamente dos cuerpos dinámicos. Las formas no estáticas se caen si no las sujeta una junta o un force sensor.

Licencia

MIT — mira LICENSE.

La licencia MIT cubre solo este servidor. CoppeliaSim se licencia por separado con Coppelia Robotics AG, y este paquete no incluye ni redistribuye ninguna parte de él: habla con un simulador que instalas y licencias tú.