coppelia-mcp

# CoppeliaSim MCP Server A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects Claude AI to [CoppeliaSim](https://www.coppeliarobotics.com/) robotics simulator, enabling direct control of simulations through natural language. ## Requirements - CoppeliaSim 4.x - Python 3.10+ - Claude Code CLI ## Installation 1. **Install Python dependencies:** ```bash pip install -r requirements.txt ``` 2. **Enable ZMQ Remote API in CoppeliaSim:** - Open CoppeliaSim - In the scene script or via the Lua console, run: ```lua simRemoteApi.start(23000) ``` - Or go to `Plugins → ZMQ Remote API` and start it on port `23000` 3. **Configure Claude Code** — add to your `~/.claude/settings.json`: ```json { "mcpServers": { "coppelia": { "command": "python", "args": ["/absolute/path/to/coppelia_mcp.py"] } } } ``` 4. **Restart Claude Code** ## Available Tools ### Simulation Control | Tool | Description | |------|-------------| | `start_simulation` | Start the simulation | | `stop_simulation` | Stop the simulation | | `pause_simulation` | Pause the simulation | | `get_simulation_state` | Get current state (running/paused/stopped) | | `get_simulation_time` | Get current simulation time in seconds | ### Scene Management | Tool | Description | |------|-------------| | `load_scene` | Load a `.ttt` or `.xml` scene file | | `close_scene` | Close the current scene | | `get_scene_objects` | List all objects (filter by type: shape, joint, dummy, sensor...) | ### Object Manipulation | Tool | Description | |------|-------------| | `get_object_handle` | Get the handle/ID of an object by name | | `get_object_position` | Get position [x, y, z] in world or relative coordinates | | `set_object_position` | Move an object to a position | | `get_object_orientation` | Get orientation (Euler angles, radians) | | `set_object_orientation` | Set orientation (Euler angles, radians) | | `remove_object` | Remove an object from the scene | ### Primitives | Tool | Description | |------|-------------| | `create_primitive` | Create a shape: `box`, `sphere`, `cylinder`, `cone`, `capsule`, `disc`, `torus` | ### Joint Control | Tool | Description | |------|-------------| | `get_joint_position` | Read joint angle/position | | `set_joint_target_position` | Set target position (rad for revolute, m for prismatic) | | `set_joint_target_velocity` | Set target velocity | ### Sensors & Scripting | Tool | Description | |------|-------------| | `read_proximity_sensor` | Read proximity sensor (detected, distance, point) | | `run_lua_script` | Execute arbitrary Lua code in CoppeliaSim | ## Usage Examples Once configured, you can ask Claude things like: - *"Start the simulation and move the robot arm to position (0.5, 0, 1.2)"* - *"Create a sphere of diameter 0.2m at the origin"* - *"List all objects in the scene"* - *"Set joint1 to 90 degrees"* - *"Read the proximity sensor and tell me what it detects"* ## Notes - CoppeliaSim must be **open and running** with ZMQ Remote API active on port `23000` before issuing commands - Default connection: `localhost:23000` — modify `get_sim()` in the script to change host/port - For complex robot behaviors, use `run_lua_script` to execute custom logic directly in the simulator ## License MIT