coppeliasim-mcp

실행 중인 CoppeliaSim 4.10 시뮬레이션을 Claude Code(또는 모든 MCP 클라이언트)가 구동할 수 있게 해주는 MCP 서버: 장면 구축, 객체 이동, 조인트 및 근접 센서 생성, 시뮬레이션 실행 및 센서 판독.

임의의 Lua 실행을 의도적으로 노출하지 않습니다. 이것이 다른 CoppeliaSim MCP 서버와의 주요 차이점입니다. 보안을 참조하세요.

도구 이름은 기본적으로 스페인어이며, 선택적으로 영어 및 포르투갈어 별칭이 있습니다 — 도구 이름 언어를 참조하세요.

Coppelia Robotics AG와 제휴, 보증, 유지보수 관계가 없습니다. CoppeliaSim은 Coppelia Robotics AG의 상표입니다. 이는 독립적인 제3자 통합입니다; 시뮬레이터 자체는 coppeliarobotics.com을 방문하세요.

요구 사항

• ZMQ 원격 API 애드온이 활성화된 CoppeliaSim 4.10이 실행 중이어야 합니다. 기본적으로 활성화되어 있으며 포트 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

또는 JSON 구성을 읽는 모든 MCP 클라이언트의 경우:

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

구성

모든 설정은 선택적 환경 변수입니다. 작업 디렉토리의 .env 파일에도 넣을 수 있습니다 — .env.example 참조.

도구

시뮬레이션 제어 — iniciar_simulacion, detener_simulacion, pausar_simulacion, estado_simulacion, tiempo_simulacion

장면 — cargar_escena, cerrar_escena

객체 — listar_objetos, obtener_posicion, fijar_posicion, obtener_orientacion, fijar_orientacion, crear_primitiva, eliminar_objeto, emparentar_objeto, fijar_detectable

조인트 — obtener_posicion_junta, fijar_objetivo_junta, fijar_velocidad_junta, obtener_fuerza_junta

근접 센서 — 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를 참조하세요.

보안

CoppeliaSim의 Lua 환경은 os와 io에 접근할 수 있습니다. 따라서 임의의 Lua를 실행하는 도구는 모든 프롬프트 인젝션(예: 모델이 검사하도록 요청받은 제3자 .ttt 장면에 포함된 텍스트)을 사용자 머신에서의 명령 실행으로 바꿉니다. 이 서버에는 의도적으로 그러한 도구가 없습니다.

나머지 표면도 의도적으로 좁습니다:

• cargar_escena는 COPPELIA_DIRECTORIO_ESCENAS와 비교하기 전에 경로를 확인합니다(Path.resolve(strict=True)). 따라서 ../.. 및 심볼릭 링크로 벗어날 수 없으며 장면 확장자만 허용합니다.

• COPPELIA_MODO_LECTURA=1은 모든 변경 도구를 한 번에 비활성화합니다.

• 장면 디렉토리는 홈 디렉토리가 아닌 작업 디렉토리로 기본 설정됩니다.

디버깅 시간을 절약하는 메모

도구가 직접 표면화하는 CoppeliaSim API에서 쉽게 잘못 이해할 수 있는 사항:

• leer_sensor_proximidad는 감지하지 않습니다. 시뮬레이터의 마지막 센서 패스 결과를 반환하므로 시뮬레이션이 중지된 상태에서는 항상 아무것도 없다고 보고합니다. 필요 시 감지하려면 comprobar_sensor_proximidad를 사용하세요.

• 객체는 근접 센서에 감지되려면 감지 가능으로 표시되어야 합니다. 이것이 fijar_detectable의 용도이며, 센서가 "작동하지 않는" 일반적인 이유입니다.

• 수평으로 향하는 넓은 콘은 장애물보다 먼저 바닥을 봅니다. 반각 a와 센서 높이 h에서 바닥은 *h / tan(a)*에서 콘에 들어옵니다. 이것이 센서 범위 아래에 있으면 센서는 지면을 보고합니다.

• 부모 재지정은 형제 경로의 번호를 다시 매깁니다. /Cylinder[1]을 섀시에 매단 후 /Cylinder[3]이 /Cylinder[1]이 될 수 있습니다. 연속된 emparentar_objeto 호출 사이에 객체를 다시 나열하거나 핸들을 미리 확인하세요.

• 부모 지정은 두 동적 형태를 단단히 연결하지 않습니다. 비정적 형태는 조인트나 포스 센서로 제약되지 않으면 떨어집니다.

릴리스

게시는 태그 푸시 시 .github/workflows/publicar.yml을 통해 실행됩니다:

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

워크플로우는 태그와 pyproject.toml의 버전이 일치하지 않으면 게시를 거부하고, Python 3.10 및 3.13에서 빌드된 휠을 설치하고, scripts/prueba_humo.py를 실행합니다 — MCP 핸드셰이크와 시뮬레이터가 없는 상태에서 호출이 멈추지 않고 응답하는지 확인 — 그 후에 업로드합니다. PyPI 버전은 덮어쓰거나 재사용할 수 없으므로 CI에서 실패하는 것이 버전 번호를 소모하는 것보다 훨씬 저렴합니다.

Trusted Publishing(OIDC)을 통해 PyPI에 인증하므로 저장소 비밀번호에 토큰이 저장되지 않습니다.

라이선스

MIT — LICENSE 참조.

MIT 라이선스는 이 서버만을 대상으로 합니다. CoppeliaSim 자체는 Coppelia Robotics AG가 별도로 라이선스를 부여하며, 이 패키지는 그 어떤 부분도 포함하거나 재배포하지 않습니다 — 직접 설치하고 라이선스를 취득하는 시뮬레이터와 통신할 뿐입니다.

coppeliasim-mcp (스페인어)

Claude Code 또는 모든 MCP 클라이언트에서 CoppeliaSim 4.10 시뮬레이션을 관리하기 위한 MCP 서버: 장면 구축, 객체 이동, 조인트 및 근접 센서 생성, 시뮬레이션 실행 및 센서 판독.

임의의 Lua 실행을 의도적으로 노출하지 않습니다. 이것이 유통되는 다른 CoppeliaSim MCP와의 주요 차이점입니다. CoppeliaSim의 Lua는 os와 io에 접근할 수 있으므로, 그러한 도구는 모든 프롬프트 인젝션(예: 제3자 .ttt 장면 내부의 텍스트)을 사용자 머신에서의 명령 실행으로 바꿉니다.

Coppelia Robotics AG의 제휴, 보증, 유지보수 없음. CoppeliaSim은 Coppelia Robotics AG의 상표입니다. 이는 독립적인 제3자 통합입니다; 시뮬레이터는 coppeliarobotics.com을 방문하세요.

요구 사항

• ZMQ 원격 API 애드온이 활성화된 CoppeliaSim 4.10이 열려 있어야 합니다. 기본적으로 활성화되어 있으며 포트 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

구성

모두 선택적인 환경 변수입니다. 작업 디렉토리의 .env에도 넣을 수 있습니다 — .env.example 참조.

도구 이름 언어

도구는 스페인어로 정의됩니다. COPPELIA_IDIOMAS는 동일한 함수에 대한 영어 및 포르투갈어 별칭을 등록합니다: 로직을 복제하지 않고 이름만 추가합니다.

카탈로그는 매 요청마다 모델로 전송되므로 별칭은 꺼져 있습니다. 그리고 켜기 전에 알아야 할 점: 모델은 다른 언어로 이해하기 위해 번역된 이름이 필요하지 않습니다. 도구 이름은 식별자이지 사용자 대상 텍스트가 아닙니다 — "move the cube forward" 또는 "mova o cubo para frente"라고 요청해도 fijar_posicion을 사용합니다. 별칭은 카탈로그를 한눈에 읽거나 도구를 명시적으로 지정할 때 유용합니다.

예시

examples/carrito_diferencial.py는 장애물 회피 기능이 있는 완전한 차동 구동 카트를 구축하고 실제로 작동하는지 측정합니다. examples/README.md를 참조하세요.

디버깅 시간을 절약하는 사항

• leer_sensor_proximidad는 감지하지 않습니다. 시뮬레이터의 마지막 스캔 결과를 반환하므로 시뮬레이션이 중지된 상태에서는 항상 아무것도 없다고 말합니다. 즉시 감지하려면 comprobar_sensor_proximidad를 사용하세요.

• 객체는 근접 센서가 보려면 감지 가능으로 표시되어야 합니다. 이것이 fijar_detectable의 용도이며, "작동하지 않는" 센서의 일반적인 원인입니다.

• 수평으로 향하는 넓은 콘은 장애물보다 먼저 바닥을 봅니다. 반각 a와 센서 높이 h에서 바닥은 *h / tan(a)*에서 콘에 들어옵니다. 이것이 범위 아래에 있으면 센서는 바닥을 보고합니다.

• 부모 지정은 형제 경로의 번호를 다시 매깁니다. /Cylinder[1]을 섀시에 매단 후 /Cylinder[3]이 /Cylinder[1]이 될 수 있습니다. 호출 사이에 객체를 다시 나열하거나 계층을 건드리기 전에 핸들을 확인하세요.

• 부모 지정은 두 동적 몸체를 단단히 연결하지 않습니다. 비정적 형태는 조인트나 포스 센서로 제약되지 않으면 떨어집니다.

라이선스

MIT — LICENSE 참조.

MIT 라이선스는 이 서버만을 대상으로 합니다. CoppeliaSim은 Coppelia Robotics AG와 별도로 라이선스가 부여되며, 이 패키지는 그 어떤 부분도 포함하거나 재배포하지 않습니다: 직접 설치하고 라이선스를 취득하는 시뮬레이터와 통신할 뿐입니다.