coppeliasim-mcp

MCP-сервер, позволяющий Claude Code (или любому MCP-клиенту) управлять запущенной симуляцией CoppeliaSim 4.10: создавать сцены, перемещать объекты, создавать шарниры и датчики приближения, запускать симуляцию и считывать показания датчиков.

Выполнение произвольного Lua намеренно не предусмотрено. Это главное отличие от других MCP-серверов для CoppeliaSim. См. Security.

Не является частью Coppelia Robotics AG, не одобрено и не поддерживается ею. CoppeliaSim является товарным знаком Coppelia Robotics AG. Это независимая сторонняя интеграция; сам симулятор доступен на coppeliarobotics.com.

Требования

• CoppeliaSim 4.10 в запущенном состоянии, сактивным аддоном ZMQ remote API. Он поставляется включённым по умолчанию и слушает порт 23000.

• Python 3.10 или новее.

Related MCP server: Robonine MCP Server

Установка

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

# Or install it
pip install coppeliasim-mcp

Зарегистрируйте его в Claude Code:

claude mcp add coppelia -- uvx coppeliasim-mcp

Или для любого MCP-клиента, читающего JSON-конфигурацию:

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

Конфигурация

Все настройки задаются необязательными переменными окружения. Их также можно разместить в файле .env в рабочем каталоге — см. .env.example.

Tools

Simulation control — iniciar_simulacion, detener_simulacion, pausar_simulacion, estado_simulacion, tiempo_simulacion

Scenes — cargar_escena, cerrar_escena

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

Joints — obtener_posicion_junta, fijar_objetivo_junta, fijar_velocidad_junta, obtener_fuerza_junta

Proximity sensors — crear_sensor_proximidad, leer_sensor_proximidad, comprobar_sensor_proximidad

Языки имён инструментов

Инструменты определены на испанском (crear_primitiva, leer_sensor_proximidad, …). Установка COPPELIA_IDIOMAS регистрирует алиасы на английском и португальском, которые указывают на те же самые функции — никакой дублирующейся логики, просто больше имён в каталоге.

Каталог отправляется модели при каждом запросе, поэтому алиасы по умолчанию выключены. Это стоит знать заранее: модели не нужны переведённые имена, чтобы понимать вас на другом языке. Имена инструментов — это идентификаторы, а не пользовательский текст: попросите «move the cube forward» или «mova o cubo para frente» — и она в любом случае обратится к fijar_posicion. Алиасы полезны, когда вы хотите просмотреть каталог целиком или явно назвать инструмент в промпте.

Примеры

examples/carrito_diferencial.py создаёт полноценного робота с дифференциальным приводом и объездом препятствий, а также проверяет, действительно ли он работает. См. examples/README.md.

Вопросы безопасности

Lua-окружение CoppeliaSim имеет доступ к os и io. Поэтому инструмент, выполняющий произвольный Lua, превращает любую prompt-injection — например, текст, встроенный в стороннюю сцену .ttt, которую модель попросили изучить, — в выполнение команд на вашей машине. В этом сервере такого инструмента нет, и это сделано намеренно.

Остальная поверхность намеренно сужена:

• cargar_escena преобразует путь (Path.resolve(strict=True)) до сравнения с COPPELIA_DIRECTORIO_ESCENAS, поэтому ../.. и симлинки не могут выйти за его пределы; принимаются только расширения сцен.

• COPPELIA_MODO_LECTURA=1 отключает все изменяющие инструменты разом.

• Каталог сцен по умолчанию — рабочий каталог, а не ваш домашний.

Заметки, которые экономят время на отладке

Свойства API Coppelia, в которых легко ошибиться и которые инструменты сразу же проявляют:

• leer_sensor_proximidad не выполняет обнаружение. Он возвращает результат последнего срабатывания датчика симулятором, поэтому при остановленной симуляции всегда сообщает, что ничего нет. Для обнаружения по запросу используйте comprobar_sensor_proximidad.

• Объект должен быть помечен как определяемый, чтобы его увидел датчик приближения. Для этого и существует fijar_detectable; именно это чаще всего мешает датчику «работать».

• Широкий конус, направленный горизонтально, видит пол раньше, чем препятствие. При полуапертуре a и датчике на высоте h пол входит в конус на расстоянии h / tan(a). Если это меньше дальности датчика, датчик сообщает о земле.

• Смена родителя перенумеровывает пути соседних объектов. После подвешивания /Сylinder[1] к шасси /Сylinder[3] может стать /Сylinder[1]. Повторно запрашивайте список объектов, либо разрешайте хэндлы заранее.

• Родительство не является жёстким креплением двух динамических тел. Нестатические формы будут падать, если их не ограничивает сустав или датчик силы.

Публикация

Публикация происходит при передаче тега в рабочий процесс .github/workflows/publicar.yml:

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

Рабочий процесс отказывается публиковать пакет, если тег не совпадает с версией в pyproject.toml, устанавливает спиленное колесо на Python 3.10 и Python 3.13 и запускает scripts/prueba_humo.py — MCP-хендшейк и проверку того, что вызов с отсутствующим симулятором отвечает, а не зависает — перед тем как загрузить что-либо. Версию PyPI нельзя перезаписать или повторно использовать, поэтому сбой в CI всё-таки дешевле, чем просто сжечь номер версии.

Он аутентифицируется в PyPI через Trusted Publishing (OIDC), поэтому в секретах репозитория не хранится токен.

Лицензия

MIT — см. LICENSE.

Лицензия MIT распространяется только на этот сервер. Сам же CoppeliaSim лицензируется отдельно компанией Coppelia Robotics AG, а этот пакет не включает и не должен распространять его части — он общается с симулятором, который вы устанавливаете и лицензируете сами.

coppeliasim-mcp (испанский)

MCP-сервер для управления симуляцией CoppeliaSim 4.10 из Claude Code или любого тяжелого MCP-клиента: чтобы строить сцены, перемещать объекты, создавать суставы и датчики удара, запускать симуляцию и считывать данные в симуляторе.

Не предоставляет исполнение произвольного Lua — это сделано намеренно. Это главное отличие от других MCP-серверов для CoppeliaSim. У CoppeliaSim'а Lua имеет доступ к os and io, поэтому подобный инструмент превращает любой промпт-инъекцию — например, текст в третьертной сцене .ttt — в выполнение команд на вашем компьютере.

Не является частью Coppelia Robotics AG, не одобрено и не поддерживается ею. CoppeliaSim — торговый знак Coppelia Robotics AG. Это независимая сторонняя интеграция; для работы с самим симулятором переходите на coppeliarobotics.com.

Требования

• CoppeliaSim 4.10 запущен, с активным аддоном ZMQ remote API. Включён по умолчанию и прослушивает порт из 23000.

• Python 3.10 или новее.

Установка

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

Инструменты

• coppelia_power — [iniciar_simulacion], [detener_simulacion], [pausar_simulation], [estado_simulation], [tiempo_simulation].

• Сцены — [cargar_escena], [cerrar_escena].

• Объекты — [listar_objetos], [obtener_posicion], [fijar_posicion], [obtener_orientacion], [fijar_orientacion], [crear_primitiva], [eliminar_objeto], [emparentar_objeto], [fijar_detectable].

• Шарниры — [getPosicion], [fijar_objetivo_junta], [fijar_velocidad_junta], [obtener_fuerza_junta].

• Датчики близости — [crear_sensor_proximidad], [leer_sensor_proximidad], [comprobar_sensor_proximidad].

Hidden note: We need to close that line.

Языки инструментов

Инструменты определены на испанском. COPPELIA_IDIOMAS создает алиасы на английском и португальском, используя те же функции, не дублируя логику.

Каталог отправляется при каждом запросе модели, поэтому по умолчанию алиасы выключены. Это важно понимать заранее: model не нуждается в переводных именах, чтобы понимать вас на другом языке. Имена инструментов — это идентификаторы, а не отображаемый текст.

Затем некоторо

examples/carrito_diferencial.py конструирует полного робота с дифференциальным приводом и выявлением препятствий, чтобы убедиться, что он на самом деле работает. См. examples/README.md.

Заметки, которые экономят часы

• leer_sensor_proximidad не ищет. Возвращает результат последнего сканирования датчика, поэтому при остановленном симуляторе всегда сообщает, что ничего нет. Для обнаружения в момент запуска comprobar_sensor_proximidad.

• Объект должен быть заметным, тогда сенсор его увидит. Это требует fijar_detectable. Это обычная причина того, что датчик якобы «не работает».

• Горизонтально направленный широкий конус видит землю раньше, чем ваш объект. Стрелка a и высота h создают пол, входящий в конус в h / tan(a). Если это под полусканием, and that is under sensor range.

• Переродитель изменяет общие пути. При переносе /Cylinder[1] под шасси /Cylinder[3] can become /Cylinder[1].

Лицензия

MIT — см. LICENSE.

Лицензия MIT покрывает только этот сервер. Сам CoppeliaSim лицензируется отдельно через Coppelia Robotics AG, и эта библиотека не включает и не распространяет его компоненты, так как она работает с симулятором, который вы используете по своей лицензии.