coppeliasim-mcp

Un servidor MCP que permite a Claude Code (o cualquier cliente MCP) manejar una simulación de CoppeliaSim 4.10: construir escenas, mover objetos, crear juntas y sensores de proximidad, ejecutar la simulación y leer los sensores.

A propósito no expone ejecución de Lua arbitrario. Esa es la diferencia principal con otros servidores MCP de CoppeliaSim. Ver Seguridad.

Los nombres de las tools están en español por defecto, con alias opcionales en inglés y portugués — ver Idiomas de los nombres de tools.

Sin afiliación, respaldo ni mantenimiento por parte de Coppelia Robotics AG. CoppeliaSim es una marca de Coppelia Robotics AG. Esta 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 y escucha en el puerto 23000.

• Python 3.10 o superior.

Related MCP server: Robonine MCP Server

Instalación

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

# Or install it
pip install coppeliasim-mcp

Regístralo con Claude Code:

claude mcp add coppelia -- uvx coppeliasim-mcp

O, para cualquier cliente MCP que lea una configuración JSON:

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

Configuración

Todas las opciones son variables de entorno opcionales. También pueden estar en un archivo .env en el directorio de trabajo — ver .env.example.

Tools

Control de simulación — iniciar_simulacion, detener_simulacion, pausar_simulacion, estado_simulacion, tiempo_simulacion

Escenas — cargar_escena, cerrar_escena

Objetos — listar_objetos, obtener_posicion, fijar_posicion, obtener_orientacion, fijar_orientacion, crear_primitiva, eliminar_objeto, emparentar_objeto, fijar_detectable

Juntas — obtener_posicion_junta, fijar_objetivo_junta, fijar_velocidad_junta, obtener_fuerza_junta

Sensores de proximidad — crear_sensor_proximidad, leer_sensor_proximidad, comprobar_sensor_proximidad

Idiomas de los nombres de tools

Las tools se definen en español (crear_primitiva, leer_sensor_proximidad, …). Al establecer COPPELIA_IDIOMAS se registran alias en inglés y portugués que apuntan a las mismas funciones: sin lógica duplicada, solo más nombres en el catálogo.

El catálogo se envía al modelo en cada petición, así que los alias vienen desactivados por defecto. Vale la pena saberlo antes de activarlos: el modelo no necesita nombres traducidos para entenderte en otro idioma. Los nombres de las tools son identificadores, no texto de cara al usuario: pide "move the cube forward" o "mova o cubo para frente" y usará fijar_posicion de todos modos. Los alias ayudan cuando quieres leer el catálogo de un vistazo, o nombrar una tool explícitamente en un prompt.

Ejemplos

examples/carrito_diferencial.py construye un robot completo de tracción diferencial con evasión de obstáculos y mide si realmente funciona. Ver examples/README.md.

Seguridad

El entorno Lua de CoppeliaSim tiene acceso a os e io. Una tool que ejecute Lua arbitrario convierte por tanto cualquier prompt injection —por ejemplo, texto incrustado en una escena .ttt de terceros que se pide al modelo que inspeccione— en ejecución de comandos en tu máquina. Este servidor no tiene esa tool, por diseño.

El resto de la superficie es deliberadamente reducida:

• cargar_escena resuelve la ruta (Path.resolve(strict=True)) antes de compararla con COPPELIA_DIRECTORIO_ESCENAS, de modo que ../.. y los enlaces simbólicos no pueden escapar de ella, y solo acepta extensiones de escena.

• COPPELIA_MODO_LECTURA=1 deshabilita todas las tools que modifican la escena a la vez.

• El directorio de escenas por defecto es el directorio de trabajo, no tu carpeta personal.

Notas que ahorran horas de depuración

Cosas de la API de CoppeliaSim que son fáciles de hacer mal, y que las tools exponen directamente:

• leer_sensor_proximidad no detecta. Devuelve el resultado del último barrido del simulador, así que con la simulación detenida siempre informa de que no hay nada. Usa comprobar_sensor_proximidad para detectar bajo demanda.

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

• Un cono ancho apuntando horizontalmente ve el suelo antes que tu obstáculo. Con media apertura a y el sensor a una altura h, el suelo entra en el cono a h / tan(a). Si eso está por debajo del alcance del sensor, el sensor informa del suelo.

• Re-emparentar renumera las rutas de los hermanos. Después de colgar /Cylinder[1] de un chasis, /Cylinder[3] puede convertirse en /Cylinder[1]. Vuelve a listar los objetos entre llamadas sucesivas a emparentar_objeto, o resuelve los handles por adelantado.

• Emparentar no une rígidamente dos formas dinámicas. Las formas no estáticas se caen a menos que estén sujetas por una junta o un sensor de fuerza.

Publicación

La publicación se ejecuta con un push de etiqueta (tag), a través de .github/workflows/publicar.yml:

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

El flujo de trabajo se niega a publicar cuando la etiqueta y la versión en pyproject.toml no coinciden, instala la rueda compilada en Python 3.10 y 3.13, y ejecuta scripts/prueba_humo.py — un handshake de MCP más una comprobación de que una llamada sin simulador presente responde en lugar de colgarse — antes de subir nada. Una versión de PyPI no se puede sobrescribir ni reutilizar, así que fallar en CI es mucho más barato que quemar un número de versión.

Se autentica con PyPI mediante Trusted Publishing (OIDC), por lo que no hay ningún token almacenado en los secretos del repositorio.

Licencia

MIT — ver LICENSE.

La licencia MIT cubre solo este servidor. CoppeliaSim en sí tiene su propia licencia de Coppelia Robotics AG, y este paquete no incluye ni redistribuye ninguna parte del mismo: se comunica con un simulador que instalas y licencias tú mismo.

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