A Three.js visualization app that lets Claude control 3D models in real-time via MCP.
Features: Interactive rotation/zoom • Real-time MCP updates
Requirements: Node.js v18+, npm, and the hello3dmcp-server running
npm install
npm run devOpen http://localhost:5173 — the app auto-connects to the MCP server at ws://localhost:3001.
npm run build # Creates optimized dist/ folder
npm run preview # Preview the production build locally| Setting | Value |
|---|---|
| Build command | npm run build |
| Publish directory | dist |
| Environment variable | VITE_WS_URL=ws://localhost:3001 |
src/
├── Application.js # Main app + WebSocket integration
├── SceneManager.js # Scene & model manipulation
├── WebSocketClient.js # Server communication
├── Model.js # Model class
├── CameraController.js # Camera controls
├── RotationController.js # Rotation handling
├── AreaLight.js # Lighting
├── RayPicker.js # Click/touch interactions
├── InteractionModeManager.js
├── constants.js
├── main.js # Entry point
├── style.scss
└── utils/
├── color/
└── coordinates/
public/models/ # 3D model assets
On connect, the frontend registers its session:
{ "type": "registerSession", "sessionId": "<session-id>" }changeColor · changeSize · scaleModel · changeBackgroundColor · setKeyLightIntensity · setKeyLightColor · [more in MCP server docs]
Server requests state:
{ "type": "requestState", "requestId": "<id>", "forceRefresh": false }Frontend responds:
{ "type": "stateResponse", "requestId": "<id>", "state": { ... } }- Start the MCP server
- Run
npm run dev - Open
http://localhost:5173?sessionId=<your-session-id>
| Problem | Check |
|---|---|
| WebSocket won't connect | MCP server running on port 3001? Correct session ID? Browser console errors? |
| Changes not appearing | WebSocket connected? Session ID matches? Server sending commands? |
- hello3dmcp-server — The MCP server that controls this frontend
MIT — Contributions welcome!