# vibe3d MCP server

> Enables an AI client to build, edit, and render 3D scenes including rooms, nodes, materials, cameras, and snapshots.

- Repository: https://github.com/vibebytes/vibe3d
- Page: https://hostedmcp.org/servers/vibebytes/vibe3d
- Transport: stdio
- Stars: 2
- License: Apache-2.0
- Latest version: 0.2.14

## Install

### Claude Code

```sh
claude mcp add --env 'VIBE3D_TOKEN=<YOUR_VIBE3D_TOKEN>' vibe3d -- npx -y @vibebyte/vibe3d-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "vibe3d": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebyte/vibe3d-mcp"
      ],
      "env": {
        "VIBE3D_TOKEN": "<YOUR_VIBE3D_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "vibe3d": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@vibebyte/vibe3d-mcp"
      ],
      "env": {
        "VIBE3D_TOKEN": "<YOUR_VIBE3D_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"vibe3d","type":"stdio","command":"npx","args":["-y","@vibebyte/vibe3d-mcp"],"env":{"VIBE3D_TOKEN":"<YOUR_VIBE3D_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "vibe3d": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebyte/vibe3d-mcp"
      ],
      "env": {
        "VIBE3D_TOKEN": "<YOUR_VIBE3D_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add vibe3d --env 'VIBE3D_TOKEN=<YOUR_VIBE3D_TOKEN>' -- npx -y @vibebyte/vibe3d-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.vibe3d]
command = "npx"
args = ["-y", "@vibebyte/vibe3d-mcp"]

[mcp_servers.vibe3d.env]
VIBE3D_TOKEN = "<YOUR_VIBE3D_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'VIBE3D_TOKEN=<YOUR_VIBE3D_TOKEN>' vibe3d npx -- -y @vibebyte/vibe3d-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "vibe3d": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebyte/vibe3d-mcp"
      ],
      "env": {
        "VIBE3D_TOKEN": "<YOUR_VIBE3D_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `VIBE3D_TOKEN` | no | yes | Daemon auth token. Prefer this over a command-line flag. |
| `VIBE3D_CHROME` | no | no | Chrome or Chromium executable. Rendering needs a system browser. |
| `VIBE3D_HOME` | no | no | Daemon home directory |
| `VIBE3D_ROOM` | no | no | Room id bound when the server starts |

## Tools (17)

- `vibe3d_help`: 查参数契约：给 tool(+op) 返回该 op 的参数字段/必填/枚举/错误码与示例；不给 tool 则列出全部工具与 op (read-only)
- `vibe3d_status`: [status] 能力探测：渲染器是否就绪、能否出 ID 通道、快照上限与载荷上限｜含 id-pass 支持；渲染或导入前先查一次 (read-only)
- `vibe3d_room`: [room] 房间：建 / 列 / 切绑定 / 看摘要 / 关 / 时间线｜op: [read] list use get timeline；[write] create close｜必填见 params 描述，字段见 vibe3d_help {tool, op}
- `vibe3d_scene`: [scene] 场景：取整份 / 摘要 / 查询节点 / 统计 / 拾取 / 体检 / 撤销重做 / 差分 / 导入导出 / 检查点 / 当前选中｜op: [read] get summary query stats pick validate diff export checkpoints selection；[write] undo redo import checkpoint restore｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜import 是整场景替换，仅用于初始化或回滚
- `vibe3d_node`: [node] 节点：建 / 改 / 删 / 克隆 / 读 / 换父 / 批量变换 / 阵列 / 吸附 / 编组 / 合并烘焙 / 按画面框拟合 / 导入模型｜op: [read] get；[write] create update delete clone reparent transform array attach group merge fit_screen import｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜create 平铺传 kind+shape+size，material 可省略（自动建）
- `vibe3d_material`: [material] 材质：按预设建 / 局部改 / 贴图与 UV / 批量指派｜op: create patch map assign｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜create 收 {preset}，id 由服务端生成；preset 任意描述词都收（如 matte-white 会归一到 concrete + 浅色），原名回读在 preset/presetNote；patch 用 baseColor（也接受 color 别名）/metalness/roughness/emissive/opacity
- `vibe3d_stage`: [stage] 舞台与环境：预设/曝光/后处理/三渲二；雾、背景、环境光、HDRI｜op: set env｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜set/env 的字段平铺在顶层（勿包成 stage:{…}）：env 传 background/ambient/fog，颜色 [r,g,b,a]，fog 是对象 {near,far}、关雾传 false
- `vibe3d_animation`: [animation] 程序化动画：定义轨道 / 播放 / 停止 / 清除 / 批量摆姿势 / 人形步态｜op: define play stop clear pose gait｜必填见 params 描述，字段见 vibe3d_help {tool, op}
- `vibe3d_fx`: [fx] 特效：粒子或光柱，建 / 删｜op: create delete｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜id 由服务端生成，不要复用已有 id
- `vibe3d_mesh`: [mesh] 网格构造：布尔 / 管体 / 背板 / 车削 / 有机体 / 倒角 / 树 / 人体 / 贴花｜op: boolean tube backdrop lathe organic bevel tree mannequin decal｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜decal 用真字形/图片；color 用 [r,g,b,a] 或 '#RRGGBB'
- `vibe3d_asset`: [asset] 资产：解析 glTF / 上传贴图模型 / 列表 / 删除｜op: [read] inspect list；[write] put delete｜必填见 params 描述，字段见 vibe3d_help {tool, op}
- `vibe3d_camera`: [camera] 机位：设置 / 保存命名机位 / 删除 / 像素投影与反投影｜op: [read] project unproject；[write] set save delete｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜set 平铺 p/target/fov，勿包成 camera:{…}；save 用命名机位
- `vibe3d_render`: [render] 渲染：快照 / 多视角 / 单资产特写 / 像素取色 / ID 通道 / 序列帧｜op: snapshot views node pick assert id_pass sequence video｜必填见 params 描述，字段见 vibe3d_help {tool, op}｜snapshot / views 前先 vibe3d_status 探能力 (read-only)
- `vibe3d_export_glb`: [export_glb] 导出 GLB（任务制，用 vibe3d_job 查进度）｜拿到 jobId 后轮询 vibe3d_job.get 到 state=done（失败看 error） (read-only)
- `vibe3d_job`: [job] 导出任务：查询 / 列表 / 取消｜op: [read] get list；[write] cancel｜必填见 params 描述，字段见 vibe3d_help {tool, op}
- `vibe3d_open_editor`: [open_editor] 打开房间编辑器（默认弹窗）｜返回 url 与 hint；open:false 只回链接 (read-only)
- `vibe3d_apply_ops`: [apply_ops] 原子批量 op（仅用于跨节点依赖；日常请用专用工具）｜嵌套载荷包在同名字段 {op:"node.create",node:{…}} / {op:"env.set",env:{…}}，不能平铺到 op 顶层（会校验失败）；ops 传数组不是 JSON 字符串。逐条操作请用专用工具

## FAQ

### What are the system requirements for vibe3d?

You need Node.js version 20 or higher to run the server.

### Does the server provide its own web browser for rendering?

No, it uses an existing system installation of Chrome, Chromium, or Edge for rendering tasks.

### How can I make sure the MCP server uses the latest version?

You should include @latest in your configuration to prevent npx from using a cached version.
