Needle MCP Server — Local AI for Needle

Talk to your AI assistant about your local and online 3D scenes! Connect Claude, Cursor, or other AI tools to the Needle MCP Server so you can explore your three.js scenes, edit objects, and get help — all through natural conversation.

Quick Start

Connect your AI assistant to the Needle MCP Server.
Start asking questions about Needle Engine, your project, or your 3D scenes!

Works with your favorite AI tools

Works with Claude Desktop, Cursor, VS Code Copilot, Antigravity, and more.

What Can You Do with the Needle MCP?

"How do I add physics to my Needle project?"
"Show me how to use WebXR in Needle Engine"
"What's the best way to deploy to Vercel?"
"Show me all the lights in my scene"
"Change the main light color to warm orange"
"Why is my scene running slowly?"

How to Connect

Using Claude Desktop

Quick setup:

Open your terminal and run:

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

Restart Claude Desktop
Look for the 🔌 icon in the bottom-right - you're connected!

Using OpenAI Codex CLI

Quick setup:

Open your terminal and run:

codex mcp add needle --url http://localhost:8424/mcp

Start using Codex — it will automatically connect to the Needle MCP server!

Using VS Code

Quick setup:

Click to Install Needle MCP in VS Code
Type #needle in Copilot chat to see Needle tools, or just ask naturally!

Local server setup (for Inspector integration)

If you want your AI to also interact with live 3D scenes via the Needle Inspector, connect to the local server instead:

Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Choose "MCP: Add Server"
Fill in the details:
- Name: needle
- Transport: http
- URL: http://localhost:8424/mcp

See Connection Modes for more details.

Using Cursor

Quick setup:

Click to Install Needle MCP in Cursor
Important: Switch to Agent Mode (not Ask Mode)
Just ask naturally — Cursor will use Needle tools automatically!

Local server setup (for Inspector integration)

If you want your AI to also interact with live 3D scenes via the Needle Inspector, connect to the local server instead:

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

Add this:

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

Restart Cursor

See Connection Modes for more details.

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

Using Antigravity

Quick setup:

Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Choose "MCP: Add Server"
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!

Built-in Tools

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

Tool	Description
Search	Search Needle Engine docs, forum posts, and community discussions by semantic similarity.
Load Needle Skill	Load the Needle Engine skill with coding guidelines, patterns, and API references.
Get Project Path	Get the path to the currently opened Unity or Blender project.
Get Scene Path	Get the path to the currently opened scene.
Get Web Project Path	Get the path to the Needle Engine web project directory.
Get Log Path	Get the path to the Unity or Blender editor log file.
Read File	Read a file from the editor or web project, with optional line range and text filter.
Search Files	Search project files by regex pattern, with optional glob and result limit.
List Files	List files in the project directories, with optional glob pattern and recursion.
Read Log	Read or search the editor log file by keyword.
Read glTF / GLB	Summarize a glTF/GLB file — nodes, meshes, materials, animations, extensions. Supports JSON pointer queries.

Blender Tools

When you're using the Needle Blender add-on, it also registers Blender-specific MCP tools. This means your AI can do more than just read files: it can inspect your Blender scene structure and help make targeted changes.

Tool	What it does
Hierarchy Search	Search the Blender hierarchy by name or object type, optionally including Needle components.
Object Details	Inspect object details including transforms, mesh stats, materials, modifiers, constraints, visibility, and Needle components.
Selected Objects	Read the current Blender selection, optionally with full object details.
Object Selection	Select one or more Blender objects by name and set the active object.
Scene Settings	Read Needle scene settings such as compression, XR, networking, rendering, and export-related options.
Add Component	Add a Needle component to a Blender object and optionally set initial properties.
Component Properties	Change one or more properties on an existing Needle component.
Object Transform	Move, rotate, and scale Blender objects.

Try prompts like:

"Show me all cameras in my Blender scene"
"What Needle components are on the selected objects?"
"Add OrbitControls to the main camera"
"Set the BoxCollider size on Cube to match the mesh"
"Which materials on this object use image textures?"

Blender + AI

If you've seen AI tools announce Blender support recently: Needle already provides this workflow. Start the Blender add-on, connect Claude, Copilot, Cursor, or OpenAI/Codex to Needle MCP, and your AI can work with real Blender scene context. You can also open Needle Cloud AI directly from Blender via Ask AI about Project.

Additional Tools when using Needle Inspector

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

The Inspector connects to the MCP server running locally (localhost:8424)
Your AI assistant can query the Inspector for scene information
The AI sees the same hierarchy, objects, and properties that you see
When you ask the AI to make changes, it sends commands through the Inspector
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.

Advanced: Connection Modes

The Needle MCP Server supports two connection modes. Both provide the full set of tools. The main difference is how they run.

Local Server (HTTP/SSE)

npx needle-cloud start

Runs a persistent local server on localhost:8424. Your AI client connects via HTTP.

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. See the setup instructions above to connect your AI client.

stdio

npx needle-cloud mcp

Your AI client spawns the process directly — no server to start or keep running.

To use stdio mode, configure your AI client with:

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

Looking for something else?

AI for Needle Engine — Coding skills, prompt files, and AI workflows
Needle Inspector for Chrome — Chat with your AI about live 3D scenes
three.js Integration — Using Needle with any three.js project