从Claude Desktop到VS Code、Cline、Codex:Blockbench MCP全平台客户端接入配置清单(附Windows避坑)
从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 插件
无头模式可跳过本步,直接看客户端配置。
- 打开 Blockbench 桌面版(版本需 ≥ 5.0);
- 进入
File>Plugins,选择 Load Plugin from URL; - 粘贴插件安装地址(Stable 稳定版,见 docs/llms/install.md),点击加载;
- 在
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 助手就能开口"建模"了。