|
| 1 | +<br/> |
| 2 | + |
| 3 | +<div class="centered" style="display: flex; |
| 4 | + align-items: center; |
| 5 | + gap: 20px; |
| 6 | + font-size: 2em; |
| 7 | + font-weight: 100;"> |
| 8 | + <img src="/logo.png" style="max-height:70px;" title="Needle Logo" alt="Needle Logo"/> + |
| 9 | + <img src="/imgs/mcp-logo.webp" style="max-height:70px;" title="MCP Logo" alt="MCP Logo"/> |
| 10 | +</div> |
| 11 | + |
| 12 | +# Needle MCP Server — Local AI for Needle |
| 13 | + |
| 14 | +Talk to your AI assistant about your 3D scenes! Connect Claude, Cursor, or other AI tools to the Needle Inspector so you can explore your three.js scenes, edit objects, and get help - all through natural conversation. |
| 15 | + |
| 16 | +### Quick Start |
| 17 | + |
| 18 | +1. Start the local MCP server: |
| 19 | + ```bash |
| 20 | + npx needle-cloud start |
| 21 | + ``` |
| 22 | + |
| 23 | +2. Connect your AI assistant using the instructions below |
| 24 | + |
| 25 | +3. Optional: Install the [Needle Inspector for Chrome](./needle-inspector.md) to chat with your AI about any three.js scene in the browser. |
| 26 | + |
| 27 | +:::tip Works with your favorite AI tools |
| 28 | +Works with Claude Desktop, Cursor, VS Code Copilot, Antigravity, and more. |
| 29 | +::: |
| 30 | + |
| 31 | + |
| 32 | +## What Can You Do? |
| 33 | + |
| 34 | +Once connected, open the Needle Inspector on any three.js webpage and chat naturally with your AI assistant: |
| 35 | + |
| 36 | +- **Explore 3D scenes**: "Show me all the lights in my scene" |
| 37 | +- **Inspect objects**: "What materials are used in this scene?" |
| 38 | +- **Edit properties**: "Change the main light color to warm orange" |
| 39 | +- **Get creative help**: "How can I make this scene look more realistic?" |
| 40 | +- **Optimize performance**: "Why is my scene running slowly?" |
| 41 | +- **Learn techniques**: "How do I add reflections to this material?" |
| 42 | +- **Debug issues**: "This object looks weird, what's wrong with it?" |
| 43 | + |
| 44 | +Your AI can actually see your 3D scene through the Inspector and help you work with specific objects, materials, lighting, and settings in real-time. |
| 45 | + |
| 46 | + |
| 47 | +## How to Connect |
| 48 | + |
| 49 | +<!-- ### Using Claude Desktop |
| 50 | +
|
| 51 | +**Quick setup:** |
| 52 | +
|
| 53 | +1. Open your terminal and run: |
| 54 | + ```bash |
| 55 | + claude mcp add --scope user --transport http needle http://localhost:8424/mcp |
| 56 | + ``` |
| 57 | +
|
| 58 | +2. Restart Claude Desktop |
| 59 | +
|
| 60 | +3. Look for the 🔌 icon in the bottom-right - you're connected! |
| 61 | +
|
| 62 | +**Manual setup:** |
| 63 | +
|
| 64 | +If the quick setup doesn't work, you can add Needle manually: |
| 65 | +
|
| 66 | +1. Find your Claude settings file: |
| 67 | + - **Mac**: Open `~/Library/Application Support/Claude/claude_desktop_config.json` |
| 68 | + - **Windows**: Open `%APPDATA%\Claude\claude_desktop_config.json` |
| 69 | +
|
| 70 | +2. Add Needle to the file: |
| 71 | + ```json |
| 72 | + { |
| 73 | + "mcpServers": { |
| 74 | + "needle": { |
| 75 | + "url": "http://localhost:8424/mcp" |
| 76 | + } |
| 77 | + } |
| 78 | + } |
| 79 | + ``` |
| 80 | +
|
| 81 | +3. Restart Claude Desktop |
| 82 | +
|
| 83 | +Try it out: *"What objects are in my three.js scene?"* |
| 84 | +
|
| 85 | +:::tip |
| 86 | +Claude will ask before using any tools - you stay in control! |
| 87 | +::: --> |
| 88 | + |
| 89 | + |
| 90 | +### Using Cursor |
| 91 | + |
| 92 | +**Quick setup:** |
| 93 | + |
| 94 | +1. In Cursor, go to Settings → MCP |
| 95 | +2. Look for Needle in the server list and install it |
| 96 | + |
| 97 | +**Manual setup:** |
| 98 | + |
| 99 | +1. In your project folder, create a file: `.cursor/mcp.json` |
| 100 | + |
| 101 | +2. Add this: |
| 102 | + ```json |
| 103 | + { |
| 104 | + "mcpServers": { |
| 105 | + "needle": { |
| 106 | + "transport": "http", |
| 107 | + "url": "http://localhost:8424/mcp" |
| 108 | + } |
| 109 | + } |
| 110 | + } |
| 111 | + ``` |
| 112 | + |
| 113 | +3. Restart Cursor |
| 114 | + |
| 115 | +4. **Important**: Switch to Agent Mode (not Ask Mode) |
| 116 | + |
| 117 | +Try it: *"Show me all the meshes in my scene"* |
| 118 | + |
| 119 | + |
| 120 | +### Using VS Code |
| 121 | + |
| 122 | +**Setup:** |
| 123 | + |
| 124 | +1. Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) |
| 125 | + |
| 126 | +2. Choose "Preferences: Open Settings (JSON)" |
| 127 | + |
| 128 | +3. Add this: |
| 129 | + ```json |
| 130 | + { |
| 131 | + "github.copilot.chat.mcp.servers": { |
| 132 | + "needle": { |
| 133 | + "transport": "http", |
| 134 | + "url": "http://localhost:8424/mcp" |
| 135 | + } |
| 136 | + } |
| 137 | + } |
| 138 | + ``` |
| 139 | + |
| 140 | +4. Restart VS Code |
| 141 | + |
| 142 | +**Using it:** |
| 143 | + |
| 144 | +Type `#needle` in Copilot chat to see Needle tools, or just ask naturally! |
| 145 | + |
| 146 | + |
| 147 | +### Using Antigravity |
| 148 | + |
| 149 | +**Quick setup:** |
| 150 | + |
| 151 | +1. Click the Agent pane menu |
| 152 | +2. Select "MCP Servers" |
| 153 | +3. Search for "Needle" |
| 154 | +4. Click "Install" |
| 155 | + |
| 156 | +That's it! Antigravity will connect automatically. |
| 157 | + |
| 158 | +**Manual setup:** |
| 159 | + |
| 160 | +1. Go to "Manage MCP Servers" |
| 161 | +2. Click "View raw config" |
| 162 | +3. Add Needle: |
| 163 | + ```json |
| 164 | + { |
| 165 | + "mcpServers": { |
| 166 | + "needle": { |
| 167 | + "transport": "http", |
| 168 | + "url": "http://localhost:8424/mcp" |
| 169 | + } |
| 170 | + } |
| 171 | + } |
| 172 | + ``` |
| 173 | + |
| 174 | +Antigravity is great at understanding what you want - just describe your goal! |
| 175 | + |
| 176 | + |
| 177 | +## What to Ask |
| 178 | + |
| 179 | +Here are some examples to get you started. Make sure the Needle Inspector is open in your browser with a three.js scene loaded: |
| 180 | + |
| 181 | +**Exploring scenes:** |
| 182 | +> "Show me all the lights in my scene" |
| 183 | +> "What materials am I using?" |
| 184 | +> "Find all the cameras and tell me where they're positioned" |
| 185 | +> "List all the meshes and their triangle counts" |
| 186 | +> "Which objects in my scene are invisible?" |
| 187 | +
|
| 188 | +**Editing and tweaking:** |
| 189 | +> "Change the directional light intensity to 0.5" |
| 190 | +> "Make the sphere at position (0, 1, 0) red" |
| 191 | +> "Hide all helper objects" |
| 192 | +> "Set the fog color to light blue" |
| 193 | +
|
| 194 | +**Getting creative help:** |
| 195 | +> "How can I make this look more photorealistic?" |
| 196 | +> "What's the best way to add shadows to my scene?" |
| 197 | +> "How do I create a metallic material?" |
| 198 | +> "Suggest ways to improve the lighting" |
| 199 | +
|
| 200 | +**Analyzing and debugging:** |
| 201 | +> "Why is my scene loading slowly?" |
| 202 | +> "Which objects have the most geometry?" |
| 203 | +> "Are there any materials with missing textures?" |
| 204 | +> "What's causing the low frame rate?" |
| 205 | +
|
| 206 | +**Learning:** |
| 207 | +> "Explain what this material's properties do" |
| 208 | +> "How does the environment map affect the scene?" |
| 209 | +> "What's the difference between a point light and a spot light?" |
| 210 | +> "Show me best practices for three.js lighting" |
| 211 | +
|
| 212 | +Just ask naturally - your AI assistant can see what the Inspector sees and will help you understand and modify your 3D scene. |
| 213 | + |
| 214 | + |
| 215 | +## How It Works |
| 216 | + |
| 217 | +When you have the Needle Inspector open in Chrome: |
| 218 | + |
| 219 | +1. The Inspector connects to the MCP server running locally (`localhost:8424`) |
| 220 | +2. Your AI assistant can query the Inspector for scene information |
| 221 | +3. The AI sees the same hierarchy, objects, and properties that you see |
| 222 | +4. When you ask the AI to make changes, it sends commands through the Inspector |
| 223 | +5. Changes appear instantly in your browser |
| 224 | + |
| 225 | +This creates a powerful workflow where you can use natural language to explore and modify complex 3D scenes without manually clicking through the Inspector interface. |
| 226 | + |
| 227 | + |
| 228 | +## Troubleshooting |
| 229 | + |
| 230 | +**Claude Desktop not connecting?** |
| 231 | +- Quit Claude completely and restart it (not just close the window) |
| 232 | +- Look for the 🔌 icon in the bottom-right corner - that means it's working |
| 233 | +- Make sure the MCP server is running: `npx needle-cloud start-server` |
| 234 | +- Double-check you followed the setup steps above |
| 235 | + |
| 236 | +**Cursor not seeing Needle?** |
| 237 | +- Make sure you're in Agent Mode (not Ask Mode) |
| 238 | +- Try restarting Cursor |
| 239 | +- Check that you created the `.cursor/mcp.json` file in your project |
| 240 | +- Verify the MCP server is running |
| 241 | + |
| 242 | +**VS Code not working?** |
| 243 | +- Make sure you have a recent version of VS Code (1.102 or newer) |
| 244 | +- Check that GitHub Copilot is active |
| 245 | +- Verify the MCP server is running |
| 246 | + |
| 247 | +**Can't see scene information?** |
| 248 | +- Open the Needle Inspector extension in your browser |
| 249 | +- Make sure you're viewing a page with a three.js scene |
| 250 | +- The Inspector should show the scene hierarchy - if not, try refreshing the page |
| 251 | +- Check the browser console for any error messages |
| 252 | + |
| 253 | +**AI says it can't access the scene:** |
| 254 | +- Verify the Needle Inspector is open and showing your scene |
| 255 | +- Make sure the MCP server is running (`npx needle-cloud start-server`) |
| 256 | +- Try closing and reopening the Inspector |
| 257 | +- Check that your AI tool is properly configured with the MCP server URL |
| 258 | + |
| 259 | + |
| 260 | +## Example Workflow |
| 261 | + |
| 262 | +Here's a typical workflow using AI with the Needle Inspector: |
| 263 | + |
| 264 | +1. **Open your scene**: Load a webpage with your three.js project |
| 265 | +2. **Launch Inspector**: Click the Needle Inspector extension icon |
| 266 | +3. **Ask for an overview**: *"What's in this scene?"* |
| 267 | +4. **Explore specifics**: *"Show me the properties of the main camera"* |
| 268 | +5. **Make changes**: *"Adjust the fog density to 0.02"* |
| 269 | +6. **Get suggestions**: *"How can I improve performance here?"* |
| 270 | +7. **Learn**: *"Explain what the roughness property does on this material"* |
| 271 | + |
| 272 | +The AI becomes your assistant, helping you understand, debug, and improve your 3D content through conversation. |
| 273 | + |
| 274 | + |
| 275 | +## What's Next? |
| 276 | + |
| 277 | +Now that you're connected: |
| 278 | +- Open the Needle Inspector on any three.js website |
| 279 | +- Try asking about the scene structure |
| 280 | +- Get AI help with tweaking materials and lighting |
| 281 | +- Ask for optimization suggestions |
| 282 | +- Learn three.js concepts by exploring real examples |
| 283 | + |
| 284 | +For more help: |
| 285 | +- [Needle Engine Docs](/index.md) |
| 286 | +- [Needle Inspector Guide](../three/needle-devtools-for-threejs-chrome-extension.md) |
| 287 | +- [three.js Integration](../three/index.md) |
| 288 | + |
| 289 | +:::tip Using Needle Engine? |
| 290 | +The Inspector has special features when used with Needle Engine projects, and the AI can help you work with Needle-specific components, networking, and XR features. |
| 291 | +::: |
0 commit comments