Nova3D

警告

已迁移： 开发工作已转至 Nova3D monorepo： https://github.com/RareSense/Nova3D/tree/main/mcp

nova3d-mcp

面向 AI Agent 的结构化、部件感知型 3D 生成。

nova3d-mcp 是一个 MCP 服务，可将 Nova3D 的生成流水线作为可调用工具，集成到 Codex、Cursor、VS Code、Visual Studio、Claude Code 和其他兼容 MCP 的 Agent 中。

只需调用一次工具。生成的洗衣机将包含单独命名的滚筒、机门、控制面板和软管连接器，可分别编辑，而非融合成一个整体。

---

快速开始

Claude Code：

1. 运行 claude mcp add nova3d -- uvx nova3d-mcp
2. 在 Claude 中调用 nova3d_login
3. 完成 Nova3D 浏览器登录流程
4. 然后调用 nova3d_status

其他 MCP 客户端：

• 查看安装，了解针对各客户端的设置方法
• 然后按照通用的首次运行步骤操作

---

为什么选择 Nova3D

如今，各大 AI 3D 生成器生成的都是网格块——融合成一个整体的物体，渲染出来看似合理，但一旦尝试编辑、绑定骨骼或接入流水线，就会崩溃。

Nova3D 与众不同。它不采用「扩散 → 网格」的方式，而是运行：

prompt / image
      ↓
LLM writes Blender Python construction code
      ↓
headless Blender executes + validates + repairs
      ↓
structured GLB — named parts, intact hierarchy, real joints

最终生成的 3D 资产能够经受真实工作流的考验：游戏引擎、配置器、机器人仿真、AR 场景。部件有名称，层级完整，关节真实。你可以更改单个组件，而无需重新生成所有内容。

---

支持的客户端

客户端	状态	安装方式	预览方式
Codex	支持	codex mcp add 或 Codex MCP 配置	浏览器 conversation_url
Cursor	支持	.cursor/mcp.json 或 ~/.cursor/mcp.json	浏览器 conversation_url
VS Code	支持	.vscode/mcp.json、MCP: Add Server 或 code --add-mcp	浏览器 conversation_url
Visual Studio	支持	.mcp.json 或 Visual Studio MCP UI	浏览器 conversation_url
Claude Code	支持	claude mcp add	浏览器 conversation_url

Nova3D 在 MCP 客户端中运行，但模型检查需要通过返回的 conversation_url，在托管的浏览器查看器中进行。此仓库目前不提供嵌入式 IDE 原生 3D 视口。

---

安装

先在客户端中添加 MCP 服务。这一步只会注册服务，不会完成 Nova3D 账户的初始设置。

Codex

codex mcp add nova3d -- uvx nova3d-mcp

Codex 还支持通过 ~/.codex/config.toml 配置 MCP。如果你更喜欢使用配置文件而非 CLI，请使用 Codex 的 MCP 配置入口，并将其指向相同的 stdio 命令：uvx nova3d-mcp。

Claude Code

claude mcp add nova3d -- uvx nova3d-mcp

Cursor

在项目中创建 .cursor/mcp.json，或创建 ~/.cursor/mcp.json 进行全局安装：

{
  "mcpServers": {
    "nova3d": {
      "command": "uvx",
      "args": ["nova3d-mcp"]
    }
  }
}

VS Code

选项 A：从命令行添加服务：

code --add-mcp "{\"name\":\"nova3d\",\"command\":\"uvx\",\"args\":[\"nova3d-mcp\"]}"

选项 B：在工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "nova3d": {
      "command": "uvx",
      "args": ["nova3d-mcp"]
    }
  }
}

你也可以在命令面板中使用 MCP: Add Server。

Visual Studio

创建 <SOLUTIONDIR>/.mcp.json 或 %USERPROFILE%/.mcp.json：

{
  "servers": {
    "nova3d": {
      "command": "uvx",
      "args": ["nova3d-mcp"]
    }
  }
}

你也可以通过 Visual Studio MCP UI 添加服务，提供 stdio 命令 uvx 和参数 ["nova3d-mcp"]。

在任意客户端中安装服务后，下一步是在该客户端中调用 nova3d_login 或 nova3d_setup。仅完成安装并不能完成 Nova3D 的初始设置。

首次运行

在任意客户端中安装 MCP 服务后：

1. 调用 nova3d_login
2. 在打开的浏览器标签页中完成 Nova3D 登录流程
3. 调用 nova3d_status
4. 如果 next_action == "purchase_credits"，请访问返回的购买链接
5. 当 authenticated: true 且 generation_ready: true 时，开始使用 generate_3d

重要事项：

• 安装 MCP 服务和完成 Nova3D 登录是两个独立步骤。
• nova3d_login 会打开浏览器标签页；在本地 MCP 会话设置仍在确认期间，可能会返回 login_pending_confirmation: true
• 如果浏览器登录已完成，但登录是否完成仍不明确，请在重试或考虑手动备用方案前调用 nova3d_status。
• 仅当环境不支持浏览器/回环身份验证时，才将 NOVA3D_TOKEN 用作高级/手动备用方案。

面向 AI 助手

如果你正在帮助用户设置 Nova3D MCP：

1. 确保客户端中已安装 nova3d MCP 服务
2. 调用 nova3d_login
3. 告知用户将打开一个浏览器标签页，他们必须在那里完成登录
4. 浏览器登录后，调用 nova3d_status
5. 如果 next_action == "purchase_credits"，请引导用户访问返回的 URL
6. 仅当 authenticated: true 且 generation_ready: true 时，才继续使用 generate_3d
7. 仅当浏览器/回环身份验证不可用时，才建议手动设置 NOVA3D_TOKEN

入门决策树

• 如果 nova3d_login 返回 login_pending_confirmation: true
  • 完成浏览器登录流程
  • 然后调用 nova3d_status
• 如果 nova3d_status.next_action == "sign_in"
  • 调用 nova3d_login
• 如果 nova3d_status.next_action == "session_expired"
  • 再次调用 nova3d_login
• 如果 nova3d_status.next_action == "purchase_credits"
  • 访问返回的购买 URL
• 如果 nova3d_status.next_action == null 且 generation_ready == true
  • 继续使用 generate_3d

本地安装

如果你希望从源代码安装，而不是使用 uvx，请克隆代码库并在本地 安装软件包：

git clone https://github.com/RareSense/nova3d-mcp.git
cd nova3d-mcp
python3.10 -m venv .venv && source .venv/bin/activate
pip install .

然后，在上方的客户端示例中，将 uvx nova3d-mcp 替换为你环境中的本地 nova3d-mcp 可执行文件。

典型工作流

完成入门设置后，将类似这样的提示词传给你的 AI Agent：

Generate a vending machine with separate door, glass panel, coin slot,
button grid, frame, and interior shelving.

Agent 会调用 generate_3d。你会收到：

{
  "glb_url": "https://nova3d.xyz/assets/abc123.glb",
  "conversation_url": "https://app.nova3d.xyz/chat/conv-...",
  "parts": ["door", "glass_panel", "coin_slot", "button_grid", "frame", "shelf_1", "shelf_2"],
  "joint_count": 1,
  "code_artifact": { ... },
  "workflow_id": "state-..."
}

• conversation_url — 你在 Nova3D 应用中的编辑会话，其中已加载生成的模型和编辑历史。此资产后续的所有 regenerate_part、add_part 和 articulate_model 调用都会关联到同一会话。

---

配置说明

• conversation_url 是检查生成资产的标准支持方式——它会在 Nova3D 应用中打开已完整加载的编辑会话。
• 推荐的入门方式是通过 nova3d_login 使用浏览器登录，然后通过 nova3d_status 确认额度和就绪状态。
• nova3d_login 会打开浏览器标签页，并通过回环回调启动本地 MCP 会话设置。
• nova3d_status 是检查身份验证、额度和就绪状态的标准后续步骤。
• 尽可能避免将密钥放入已签入版本控制的工作区配置中。优先使用 每用户配置文件或由客户端管理的环境变量。
• 如果你的编辑器支持受源代码控制的 MCP 配置，请提交服务条目；仅在高级/手动备用方案中，为每位用户单独注入 NOVA3D_TOKEN。

---

故障排查

问题	检查内容
生成前提示登录	调用 nova3d_login，然后通过 nova3d_status 再次检查
nova3d_login 返回 login_pending_confirmation: true	完成浏览器登录步骤，然后调用 nova3d_status
已完成浏览器登录，但 nova3d_login 未确认完成	现在调用 nova3d_status。如果仍显示未登录，请重试 nova3d_login
提示需要点数	使用 nova3d_status 返回的购买链接
启动时认证失败	使用 nova3d_login 重新登录，或在 https://app.nova3d.xyz/api-key 确认手动密钥
找不到 uvx	安装 uv，或使用虚拟环境中的本地 nova3d-mcp 可执行文件
编辑器内没有 3D 预览	在浏览器中打开返回的 conversation_url；这是受支持的预览方式

---

工具

generate_3d

根据文本（以及可选的参考图像）生成结构化 3D 资产。 初始生成通过 Nova3D 的付费 GraphFlow v2 工作流运行。此 MCP 服务不提供 BYOK／提供商密钥生成。

参数	类型	必填	描述
prompt	string	✓	资产描述。请具体说明各个部件。
model	string		付费路由预设："gemini"（默认）· "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5"
image_base64	string		纯 base64 格式的参考图像；服务会将其转换为 v2 image_artifact 数据 URL 格式
image_mime	string		例如 "image/jpeg"

返回： glb_url、conversation_url、parts、joint_count、code_artifact、model_artifact、workflow_id。将 code_artifact 传给任意编辑工具。打开 conversation_url，即可在 Nova3D 应用中查看此资产的完整编辑历史。

---

regenerate_part

重新生成指定部件，而不重建整个资产。

参数	类型	必填	描述
code_artifact	object	✓	来自先前 generate_3d 的结果
part_type	string	✓	部件名称，例如 "door"、"handle"
description	string	✓	描述新部件应呈现的样子
model	string		"gemini"（默认）· "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5"

查找部件名称： 打开生成结果中的 conversation_url， 并检查模型查看器——每个网格都有标签。请将准确名称用作 part_type。

---

add_part

向现有资产添加新组件。

参数	类型	必填	描述
code_artifact	object	✓	来自先前生成结果
description	string	✓	描述新部件及其放置位置
model	string		"gemini"（默认）· "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5"

---

articulate_model

为现有资产添加关节、铰链或旋转结构。

参数	类型	必填	描述
code_artifact	object	✓	来自先前生成结果
articulation_request	string	✓	描述哪些部分应如何运动
model_url	string		来自先前生成的 glb_url。提供此项或 model_artifact。
model_artifact	object		来自先前生成的 model_artifact。提供此项或 model_url。
model	string		"gemini"（默认）· "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5"
selected_meshes	list		要添加活动结构的特定网格名称

---

get_generation_status

通过 ID 检查正在运行的工作流状态。

参数	类型	必填	描述
workflow_id	string	✓	来自任意先前生成工具

---

nova3d_login

启动首选的基于浏览器的 Nova3D 登录流程，并保存本地 MCP 会话。 此操作会打开一个浏览器标签页。如果浏览器流程已完成，但本地完成状态不明确， 请先调用 nova3d_status，再使用手动令牌回退方式。

---

nova3d_status

返回规范的 Nova3D 入门/就绪状态，包括身份、额度、生成就绪情况以及下一步建议操作。

---

nova3d_logout

清除本地存储的 MCP 会话。此操作不会移除 MCP 配置中的高级/手动 NOVA3D_TOKEN。

---

典型工作流

1. generate_3d("robot dog with four legs, head, torso, and tail")
   → glb_url, conversation_url, parts, code_artifact

2. Open conversation_url in browser
   → see named parts, identify what needs changing

3. regenerate_part(code_artifact, part_type="head", description="...")
   → updated glb_url, same conversation_url

4. add_part(code_artifact, description="a wagging tail with three segments")
   → updated glb_url, parts list now includes new tail segments

5. articulate_model(code_artifact, model_url, "make legs rotate at hip joints")
   → glb_url with working joints

所有编辑工具都接受任意先前结果中的 code_artifact，并返回更新后的版本。始终传入最新的 code_artifact — 它包含用于串联各项编辑的会话状态。

---

模型参考

model 值	提供方	说明
"gemini" (默认)	Google Gemini	推荐用于空间推理
"claude-sonnet"	Anthropic	推理能力强
"claude-opus"	Anthropic	Anthropic 能力最强的模型
"claude-opus-latest"	Anthropic	最新的 Opus 版本
"gpt-5.5"	OpenAI	最新的 GPT 模型

---

环境变量

变量	必需	说明
NOVA3D_TOKEN		高级/手动回退 API 密钥，来自 https://app.nova3d.xyz/api-key
NOVA3D_API_URL		覆盖 API 基础 URL（默认值：https://nova3d.xyz/api）
NOVA3D_APP_URL		覆盖对话链接的应用 URL（默认值：https://app.nova3d.xyz）

---

与 blender-mcp 的区别

blender-mcp（21.9k ★）为 AI Agent 提供对本地运行的 Blender 实例的远程控制。它要求安装 Blender，生成非结构化输出，并继承了原始 LLM → Blender 代码生成中的所有 bpy 幻觉问题。

nova3d-mcp 从根本上有所不同：

	blender-mcp	nova3d-mcp
是否需要 Blender	是	否
输出	非结构化场景	命名的分层 GLB
验证	无	服务端修复循环
部件感知	否	是 — 可命名、可寻址
关节	手动编写脚本	一等输出
托管后端	否	是

---

贡献

欢迎提交问题、PR 和工作流反馈。 github.com/RareSense/nova3d-mcp

社区 Discord：discord.gg/QEH8mzcwdR

---

许可证

MIT — 详见 LICENSE