Blender MCP Server

# Blender MCP Troubleshooting Guide ## Infinite Loop / Container Restart Issues ### Problem The Docker container keeps restarting infinitely when running the MCP server. ### Root Causes 1. **Unhandled exceptions** in the Python server causing crashes 2. **Docker auto-restart policy** causing the container to restart on failure 3. **MCP stdio communication errors** between Antigravity and the container 4. **Connection failures** to Blender addon not being handled gracefully ### Solutions Implemented #### 1. Added `--restart=no` to Docker args In `mcp_config.json`: ```json "args": [ "run", "-i", "--rm", "--restart=no", // ← Prevents auto-restart on failure "--add-host=host.docker.internal:host-gateway", "blender-mcp-server" ] ``` #### 2. Added Comprehensive Error Handling - **Logging to stderr**: All logs go to stderr to avoid interfering with MCP stdio - **Socket timeout**: 5-second timeout to prevent hanging connections - **Try-catch wrapper**: Main execution wrapped to catch fatal errors - **Graceful error responses**: Connection errors return JSON instead of crashing #### 3. Added Debugging Logs Check Docker logs to see what's happening: ```bash docker logs <container_id> ``` Or run the container manually to see stderr output: ```bash docker run -i --rm --add-host=host.docker.internal:host-gateway blender-mcp-server ``` ## Common Error Messages ### "Could not connect to Blender" **Cause**: Blender is not running or the addon is not installed/enabled. **Solution**: 1. Open Blender 2. Install the addon from `addon.py` 3. Enable the addon in Preferences → Add-ons 4. Make sure Blender is listening on port 9876 ### "Timeout connecting to Blender" **Cause**: Blender is running but not responding within 5 seconds. **Solution**: 1. Check if Blender is frozen 2. Restart Blender 3. Check if port 9876 is blocked by firewall ### "Invalid trailing data at end of stream" **Cause**: MCP protocol error, usually from malformed JSON output. **Solution**: 1. Check that nothing is printing to stdout except MCP messages 2. All logging should go to stderr (already implemented) 3. Rebuild Docker image: `docker build -t blender-mcp-server .` ## Debugging Steps ### 1. Check if Blender addon is running ```python # In Blender's Python console: import socket s = socket.socket() s.bind(('127.0.0.1', 9876)) s.listen(1) # If this works, the addon is NOT running (port is free) # If this errors, the addon IS running (port is in use) ``` ### 2. Test connection manually ```bash # From Windows host: telnet host.docker.internal 9876 ``` ### 3. Check Docker logs ```bash # List running containers docker ps # View logs docker logs <container_id> # Follow logs in real-time docker logs -f <container_id> ``` ### 4. Run server outside Docker ```bash cd d:\custom-mcp\blender-mcp python server.py ``` This will show all stderr logs directly in your terminal. ## Prevention Tips 1. **Always check Blender is running** before using MCP tools 2. **Monitor stderr logs** for connection issues 3. **Use `get_blender_version()`** to test connection before complex operations 4. **Keep Docker image updated** after code changes: `docker build -t blender-mcp-server .` ## Environment Variables You can customize the Blender connection: ```json "env": { "BLENDER_HOST": "host.docker.internal", "BLENDER_PORT": "9876" } ``` Default values: - `BLENDER_HOST`: `127.0.0.1` (use `host.docker.internal` in Docker) - `BLENDER_PORT`: `9876`