从Claude Desktop到VS Code、Cline、Codex:Blockbench MCP全平台客户端接入配置清单(附Windows避坑)

原创2026-11-14 18:13:381,965 阅读

从Claude Desktop到VS Code、Cline、Codex:Blockbench MCP全平台客户端接入配置清单(附Windows避坑)

blockbench-mcp-plugin(Blockbench MCP)是一个为 Blockbench 3D 编辑器添加 MCP(Model Context Protocol)服务器的开源插件,让你用 Claude Desktop、VS Code、Cline、Codex 等 AI 客户端直接驱动 Blockbench 建模。本文提供一份可直接复制的全平台客户端接入配置清单,并专门整理了 Windows 用户最常见的 5 个避坑要点。

两种连接模式:先搞懂 HTTP 与 stdio

Blockbench MCP 提供两套服务器,可按需单选或同时使用(来源:README.md):

模式 协议 运行前提 适合场景
桌面插件(Desktop Plugin) HTTP(默认 http://localhost:3000/bb-mcp) Blockbench 桌面版正在运行且已装插件 在编辑器里实时建模、动画、贴图
无头模式(Headless) stdio 只需 Node.js + npm,无需打开 Blockbench 批量处理 .bbmodel 文件、多 Agent 并行工作
  • 桌面插件模式由编辑器内部服务器提供服务,一次只有一个 Agent 在工作;
  • 无头模式每个 Agent 启动独立进程,可并行编辑、校验、转换和渲染 .bbmodel 文件,你仍可正常使用 Blockbench(详见 headless/README.md)。

接入前准备:安装 Blockbench MCP 插件

无头模式可跳过本步,直接看客户端配置。

  1. 打开 Blockbench 桌面版(版本需 ≥ 5.0);
  2. 进入 File > Plugins,选择 Load Plugin from URL;
  3. 粘贴插件安装地址(Stable 稳定版,见 docs/llms/install.md),点击加载;
  4. 在 Settings > General 中确认两项设置:MCP Server Port(默认 3000)与 MCP Server Endpoint(默认 bb-mcp)。

⚠️ 客户端配置里的 URL 必须与这两项设置完全一致,这是最常见的"连不上"原因。设置项源码位于 ui/settings.ts。

客户端配置清单

下面所有示例中,/path/to/models 请替换为你的模型目录绝对路径(Windows 下形如 C:/Users/you/models)。

Claude Desktop 一键接入步骤

Claude Desktop 只支持 stdio 拉起进程,因此 HTTP 模式需经 mcp-remote 桥接。编辑 claude_desktop_config.json:

macOS / Linux:

{
  "mcpServers": {
    "blockbench": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/bb-mcp"]
    },
    "bbmodel": {
      "command": "npx",
      "args": ["-y", "github:jasonjgardner/blockbench-mcp-plugin", "--root", "/path/to/models"]
    }
  }
}

Windows(重点,见下文避坑):

{
  "mcpServers": {
    "blockbench": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-remote", "http://localhost:3000/bb-mcp"]
    },
    "bbmodel": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "github:jasonjgardner/blockbench-mcp-plugin", "--root", "C:/Users/you/models"]
    }
  }
}

Claude Code 用户一条命令即可:

claude mcp add blockbench --transport http http://localhost:3000/bb-mcp

VS Code 中配置 Blockbench MCP 服务器

在项目根目录创建 .vscode/mcp.json,可同时挂上 HTTP 与 stdio 两个服务器:

{
  "servers": {
    "blockbench": {
      "url": "http://localhost:3000/bb-mcp",
      "type": "http"
    },
    "bbmodel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:jasonjgardner/blockbench-mcp-plugin", "--root", "${input:rootDir}"]
    }
  },
  "inputs": [
    {
      "id": "rootDir",
      "type": "promptString",
      "description": "Root directory for headless Blockbench models",
      "default": "${workspaceFolder}/models"
    }
  ]
}

${input:rootDir} 会在启动时提示你填写模型目录,默认落在工作区的 models/ 下。

Cline 连接 Blockbench MCP 的 JSON 配置

编辑 cline_mcp_settings.json(Cline 使用 streamableHttp 类型):

{
  "mcpServers": {
    "blockbench": {
      "url": "http://localhost:3000/bb-mcp",
      "type": "streamableHttp",
      "disabled": false,
      "autoApprove": []
    },
    "bbmodel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:jasonjgardner/blockbench-mcp-plugin", "--root", "/path/to/models"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Codex 注册 MCP 服务器的命令

# 桌面插件(HTTP)
codex mcp add blockbench --url http://localhost:3000/bb-mcp

# 无头模式(stdio)
codex mcp add bbmodel -- npx -y github:jasonjgardner/blockbench-mcp-plugin --root /path/to/models

其他客户端速查(Antigravity / OpenCode / Ollama)

# Antigravity:配置 "mcpServers" 中 "serverUrl": "http://localhost:3000/bb-mcp"

# Ollama(经 ollmcp 桥接)
uvx ollmcp -u http://localhost:3000/bb-mcp

# OpenCode
opencode mcp add

完整可复制的 JSON/命令示例均以 README.md 为准,AI 助手专用的精简版安装指引见 llms-install.md。

Windows 避坑指南:5 个高频问题一次解决

坑 1:npx 启动失败(Cannot find / EACCES) Windows 上 npx 实际是 .cmd 垫片(shim),很多 MCP 客户端无法直接启动它。解决办法就是把 "command" 改为 "cmd",并在 args 最前面加 "/c", "npx",即上文 Claude Desktop 的 Windows 写法(headless/README.md 中有同样说明)。

坑 2:--root 用了相对路径或中文路径 无头模式必须传 --root,且建议用盘符绝对路径(C:/Users/you/models)。--root 同时是安全边界:服务器会拒绝访问该目录之外的任何路径(含符号链接)。

坑 3:WSL2 / 虚拟机里连不上 localhost:3000 服务器默认只监听本机回环地址(127.0.0.1 / ::1)。若客户端在 WSL2(未开启 mirrored networking)、VM 或另一台电脑上,需在 Blockbench 的 Settings > General > MCP Server Host 改为 0.0.0.0 后重载插件(实现见 server/net-security.ts)。 ⚠️ 此模式下无鉴权——任何能访问该端口的人都能调用全部工具,只在可信网络使用,并保持防火墙规则严格。

坑 4:无头渲染(bbmodel_render)报错 渲染工具基于内置 WebGPU 引擎,要求 Node 23.6+ 且需要 GPU;首次渲染会向用户缓存目录(Windows 为 %LOCALAPPDATA%\blockbench-mcp-headless)下载约 130 MB 依赖。不渲染模型可完全忽略此要求。

坑 5:端口/端点与客户端不一致 改过 MCP Server Port 或 MCP Server Endpoint 后,所有客户端配置里的 URL 都要同步修改。默认组合是 :3000/bb-mcp。

安全与使用小贴士

  • 🔒 服务器默认拒绝携带非回环 Origin/Host 头的请求,可有效防住 DNS rebinding 攻击;
  • 🚫 risky_eval 可执行客户端发来的任意 JavaScript,不信任的客户端接入前建议清空 Settings > General > Enable risky_eval;
  • 🧩 先给项目准备好贴图与分组,再让 Agent 开工,成功率更高;
  • ✂️ 在客户端中关闭用不到的工具,减少上下文干扰;
  • 💾 这是实验性技术,改动已有工程前务必备份(更多使用建议见 about.md)。

相关文档与源码索引

资源 路径
总览与全部客户端配置 README.md
无头模式工具清单与限制 headless/README.md
插件安装地址(Stable/Latest) docs/llms/install.md
使用限制与技巧 about.md
MCP 端口/端点设置项 ui/settings.ts
服务器地址解析与安全逻辑 server/net-security.ts
第三方插件扩展 MCP 工具 API docs/plugin.md
项目简介 llms.txt

把对应客户端的 JSON 复制粘贴、确认 Blockbench 正在运行,你的 AI 助手就能开口"建模"了。

登录后查看全文
blockbench-mcp-plugin