+

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

1. Configure your AI assistant to run npx -y needle-cloud mcp as an MCP server.
2. Start your AI assistant. It launches the MCP command for you. The command reuses or starts the shared local server at localhost:8424, so the Needle Inspector and editor integrations can connect too.
3. Ask about Needle Engine, your project, or your 3D scenes.

If your AI client only supports an HTTP MCP URL, see Local Server (HTTP) below.

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"
"Show me all the lights in my scene"
"Change the main light color to warm orange"
"Why is my scene running slowly?"

Your agent can also pull the edits you made by hand in the Needle Inspector and apply them to your source code — tweak a material in the browser, then ask your AI to make it permanent.

How to Connect

The stdio command npx -y needle-cloud mcp starts the shared local server when needed. For the HTTP setups below, run npx needle-cloud start first and keep it running. Unity and Blender editor integrations may already have started it.

Using Claude Code

Quick setup:

1. Open your terminal and run:

   claude mcp add --scope user --transport stdio needle -- npx -y needle-cloud mcp

2. Start or restart Claude Code. It starts the Needle MCP command automatically. Use /mcp to check the connection.

Using Claude Desktop

Open Claude Desktop Settings > Developer > Edit Config and add Needle to your MCP configuration. If you already have other servers, add the needle entry to your existing mcpServers object:

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

Save the configuration, fully quit Claude Desktop, and reopen it. It starts the MCP command when it connects; you do not need to start a separate server.

Using OpenAI Codex CLI

Quick setup:

1. Open your terminal and run:

   codex mcp add needle -- npx -y needle-cloud mcp

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

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

Quick setup:

1. Click to Install Needle MCP in Cursor

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

3. Just ask naturally — Cursor will use Needle tools automatically!

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

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!

Built-in Tools

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

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.

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?"

Additional Tools when using Needle Inspector

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.

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)

npx needle-cloud start

Starts the shared local server on localhost:8424. Connect your AI client to http://localhost:8424/mcp and keep this process running. Unity and Blender editor integrations may already have started it.

stdio

npx -y needle-cloud mcp

Use this as the command in your AI client's MCP configuration. The client starts the stdio process. It reuses the shared local server if one exists, or starts it automatically; Inspector and editor tools work through this connection too. When the AI client closes the stdio process, the shared server remains available to other apps.

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