vibe3d

vibe3d is an MCP server for building and rendering 3D scenes. One command starts the protocol server, which launches the local daemon for you.

Requires Node.js >= 20 (same as the MCP TypeScript SDK v2). Licensed under Apache-2.0.

Identity

Related MCP server: x3d-mcp

Install

npx -y @vibebyte/vibe3d-mcp@latest

The daemon listens on loopback only (127.0.0.1 / localhost).

Client config:

{
  "mcpServers": {
    "vibe3d": {
      "command": "npx",
      "args": ["-y", "@vibebyte/vibe3d-mcp@latest"]
    }
  }
}

GUI apps (Cursor, Claude Desktop) often do not load interactive shell config (~/.zshrc, nvm hooks, etc.). A wrapper like bash -lc "nvm use …" usually fails on macOS: login bash does not load zsh’s nvm. Do not put version-manager wrappers in MCP config.

Keep @latest in the config: without a version tag npx reuses its cache and never picks up new releases, even after you reload the MCP server. A newer MCP also restarts an older local daemon on start.

Make the default node / npx on the PATH those apps actually use >= 20, then use the JSON above:

1. Install Node.js 20+ with the official installer or Homebrew so the system node is already 20+; or

2. If you use a version manager, set its default to 20+ and ensure its shims are on the non-interactive PATH the GUI inherits (for example Volta’s ~/.volta/bin). nvm alias default 20 alone does not fix Cursor if nvm is only sourced in zsh.

Cursor

Use the default JSON above in .cursor/mcp.json or the user MCP config. If status stays Error, open MCP Output — a Node < 20 message means fix the default Node on the GUI PATH (options above), not the MCP JSON shape.

Claude Desktop

Same JSON in claude_desktop_config.json.

Claude Code

claude mcp add vibe3d -- npx -y @vibebyte/vibe3d-mcp@latest

VS Code

{
  "servers": {
    "vibe3d": {
      "command": "npx",
      "args": ["-y", "@vibebyte/vibe3d-mcp@latest"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector --cli npx -y @vibebyte/vibe3d-mcp@latest --method tools/list

Environment

When the MCP process starts and finds a local daemon of a different version, it stops that daemon (SIGTERM, data is flushed) and starts a matching one. Restarting the MCP therefore picks up an upgraded daemon. Rooms live only in daemon memory unless it runs with --persist (VIBE3D_PERSIST=1), so restarting a non-persistent daemon discards its rooms. --url remote daemons are never touched.

Rendering uses a system Chrome, Chromium, or Edge. The package does not download a browser. Without one, scene editing still works and vibe3d_status reports that rendering is unavailable.

Support

CLI parameters

The vibe3d command line and MCP share one capability spec. Field names are camelCase. The CLI shows them in kebab-case, so rotateStep is --rotate-step and withinBBox is --within-bbox.

Comma-separated text splits into the field's array or tuple: --tags a,b, --offset 1,0,0. A command that has both width and height also accepts --size 1280x720. Objects take JSON, or @file.

vibe3d node create r1 --shape box --size 1,2,3
vibe3d scene query r1 --material m_aaaaaaaa --parent root
vibe3d anim gait r1 @runner --style run

vibe3d help <command> prints the same descriptions as vibe3d_help. An unknown flag is an error.

Tools

The server exposes a small set of grouped tools. Each call passes op, for example vibe3d_room with op: "create". This keeps tools/list small. Unknown tool names come back as tool errors (isError) so the model can correct itself. Long renders and exports are jobs: poll vibe3d_job.

Multiple rooms and chats

One MCP process keeps one default room. While it has seen a single room, room tools may omit room_id; results marked "implicit" used that default. Once the process has seen a second room (or several chats share it), calls without room_id are rejected and list the candidates. Pass the room_id returned by your own create call on every call. An explicit room_id routes only that call and never changes the default. vibe3d_room {op:"use"} pins the default room when you know only one chat is active.

Diagnostics

npx -y @vibebyte/vibe3d-mcp@latest --doctor --json

This prints the Node version, daemon health, Chrome discovery, schema file, and version match. It does not start an MCP session.

Develop

See CONTRIBUTING.md. From this repository, with Node 20+:

CI=true pnpm install
pnpm --filter @vibebyte/vibe3d-editor build
pnpm --filter @vibebyte/vibe3d-daemon build
pnpm --filter @vibebyte/vibe3d-mcp build

pnpm install may ask to reinstall node_modules from scratch. CI=true accepts that prompt.

Security reports: SECURITY.md.