+

Needle MCP Server — Local AI for Needle

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.

Quick Start

1. Start the local MCP server:

   npx needle-cloud start

2. Connect your AI assistant using the instructions below in the How to Connect section.

3. Install the Needle Inspector for Chrome to chat with your AI about any three.js scene in the browser.

4. Visit a three.js webpage (e.g. needle.tools)

5. Ask your local AI assistant questions about the scene!

What Can You Do?

Always Available (No Inspector Required)

The MCP server provides powerful tools that work anywhere:

• Search documentation: "How do I add physics to my Needle project?"
• Find examples: "Show me how to use WebXR in Needle Engine"
• Get help: "What's the best way to deploy to Vercel?"
• Learn APIs: "How does the serializable decorator work?"

With the Inspector Open

Open the Needle Inspector on any three.js webpage to also chat about live 3D scenes:

• Explore 3D scenes: "Show me all the lights in my scene"
• Inspect objects: "What materials are used in this scene?"
• Edit properties: "Change the main light color to warm orange"
• Get creative help: "How can I make this scene look more realistic?"
• Optimize performance: "Why is my scene running slowly?"
• Learn techniques: "How do I add reflections to this material?"
• Debug issues: "This object looks weird, what's wrong with it?"

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.

How to Connect

Using Claude Desktop

Quick setup:

1. Open your terminal and run:

   claude mcp add --scope user --transport http needle http://localhost:8424/mcp

2. Restart Claude Desktop

3. Look for the 🔌 icon in the bottom-right - you're connected!

Using VS Code

Quick setup:

1. Click to Install Needle MCP in VS Code

2. Type #needle in Copilot chat to see Needle tools, or just ask naturally!

Using Cursor

1. In your project folder, create a file: .cursor/mcp.json

2. Add this:

   {
     "mcpServers": {
       "needle": {
         "transport": "http",
         "url": "http://localhost:8424/mcp"
       }
     }
   }

3. Restart Cursor

4. Important: Switch to Agent Mode (not Ask Mode)

Try it: "Show me all the meshes in my scene"

Using Antigravity

Quick setup:

1. Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)

2. Choose "MCP: Add Server"

3. Fill in the details:

   • Name: needle
   • Transport: http
   • URL: http://localhost:8424/mcp

Antigravity is great at understanding what you want - just describe your goal!

What to Ask

Documentation & Learning (Always Available)

You can ask your AI about Needle Engine anytime — no Inspector needed:

Getting started:

"How do I create my first Needle Engine project?"
"What's the difference between Unity and Blender workflows?"
"How do I deploy my project to Needle Cloud?"

APIs and features:

"How do I use the @serializable decorator?"
"What lifecycle methods are available for components?"
"How do I implement custom networking?"

Troubleshooting:

"Why isn't my texture loading?"
"How do I fix CORS issues?"
"What are common WebXR problems?"

Scene Inspection (With Inspector Open)

For these examples, make sure the Needle Inspector is open in your browser with a three.js scene loaded:

Exploring scenes:

"Show me all the lights in my scene"
"What materials am I using?"
"Find all the cameras and tell me where they're positioned"
"List all the meshes and their triangle counts"
"Which objects in my scene are invisible?"

Editing and tweaking:

"Change the directional light intensity to 0.5"
"Make the sphere at position (0, 1, 0) red"
"Hide all helper objects"
"Set the fog color to light blue"

Getting creative help:

"How can I make this look more photorealistic?"
"What's the best way to add shadows to my scene?"
"How do I create a metallic material?"
"Suggest ways to improve the lighting"

Analyzing and debugging:

"Why is my scene loading slowly?"
"Which objects have the most geometry?"
"Are there any materials with missing textures?"
"What's causing the low frame rate?"

Learning:

"Explain what this material's properties do"
"How does the environment map affect the scene?"
"What's the difference between a point light and a spot light?"
"Show me best practices for three.js lighting"

Just ask naturally - your AI assistant can see what the Inspector sees and will help you understand and modify your 3D scene.

Built-in Tools

The Needle MCP Server comes with built-in tools that are always available, even without the Inspector:

needle_search — Search Needle Knowledge Base

Search across Needle Engine documentation, forum posts, and community discussions. Returns results ranked by semantic similarity.

Example queries:

• "How to add physics components"
• "WebXR hand tracking"
• "Deploy to Vercel"
• "Custom shaders in Needle"

Parameters:

This is perfect for getting AI assistance with Needle Engine development — your AI can search the docs and provide accurate, up-to-date answers.

needle_cloud_me — Get Current User

Returns information about the currently logged-in Needle Cloud user, including name, email, and profile picture.

This is useful for AI workflows that need to know who's logged in or personalize responses.

Inspector Tools

When you have the Needle Inspector open in Chrome, additional tools become available for interacting with 3D scenes:

1. The Inspector connects to the MCP server running locally (localhost:8424)
2. Your AI assistant can query the Inspector for scene information
3. The AI sees the same hierarchy, objects, and properties that you see
4. When you ask the AI to make changes, it sends commands through the Inspector
5. Changes appear instantly in your browser

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.

See Needle Inspector for Chrome for details on the Inspector tools and capabilities.

Troubleshooting

Claude Desktop not connecting?

• Quit Claude completely and restart it (not just close the window)
• Look for the 🔌 icon in the bottom-right corner - that means it's working
• Make sure the MCP server is running: npx needle-cloud start-server
• Double-check you followed the setup steps above

Cursor not seeing Needle?

• Make sure you're in Agent Mode (not Ask Mode)
• Try restarting Cursor
• Check that you created the .cursor/mcp.json file in your project
• Verify the MCP server is running

VS Code not working?

• Make sure you have a recent version of VS Code (1.102 or newer)
• Check that GitHub Copilot is active
• Verify the MCP server is running

Can't see scene information?

• Open the Needle Inspector extension in your browser
• Make sure you're viewing a page with a three.js scene
• The Inspector should show the scene hierarchy - if not, try refreshing the page
• Check the browser console for any error messages

AI says it can't access the scene:

• Verify the Needle Inspector is open and showing your scene
• Make sure the MCP server is running (npx needle-cloud start-server)
• Try closing and reopening the Inspector
• Check that your AI tool is properly configured with the MCP server URL

Example Workflow

Here's a typical workflow using AI with the Needle Inspector:

1. Open your scene: Load a webpage with your three.js project
2. Launch Inspector: Click the Needle Inspector extension icon
3. Ask for an overview: "What's in this scene?"
4. Explore specifics: "Show me the properties of the main camera"
5. Make changes: "Adjust the fog density to 0.02"
6. Get suggestions: "How can I improve performance here?"
7. Learn: "Explain what the roughness property does on this material"

The AI becomes your assistant, helping you understand, debug, and improve your 3D content through conversation.

What's Next?

Now that you're connected:

• Open the Needle Inspector on any three.js website
• Try asking about the scene structure
• Get AI help with tweaking materials and lighting
• Ask for optimization suggestions
• Learn three.js concepts by exploring real examples

For more help:

• Needle Engine Docs
• Needle Inspector Guide
• three.js Integration

Advanced: Connection Modes

The Needle MCP Server supports two connection modes. The setup instructions above use the local server mode, which gives you the full experience including Inspector integration. But if you only need documentation search and don't plan to use the Inspector, there's a lighter alternative.

Local Server (HTTP/SSE) — Full Experience

npx needle-cloud start

Runs a persistent local server on localhost:8424. Your AI client connects via HTTP. This mode supports all tools including dynamic tools registered by the Needle Inspector at runtime — scene inspection, object editing, live debugging, etc. Use this when you're actively working with 3D scenes in the browser.

If you're using Needle Engine for Unity or Blender, the local server is usually already running on your machine — the editor integrations start it automatically for license validation and login. You just need to point your AI client to http://localhost:8424/mcp.

stdio — Lightweight, No Server Required

npx needle-cloud mcp

Your AI client spawns the process directly — no server to start or keep running. Provides the built-in tools (documentation search, account info, editor paths) but does not support Inspector tools, since there's no server for the Inspector to connect to. This is ideal for AI-assisted coding workflows where you just need quick access to Needle Engine docs and APIs.

To use stdio mode, configure your AI client with:

{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": ["-y", "needle-cloud", "mcp"]
    }
  }
}

Which should I use?