nova3d-mcp
Structured, part-aware 3D generation for AI agents.
nova3d-mcp is an MCP server that exposes
Nova3D's generation pipeline as a callable tool inside
Codex, Cursor, VS Code, Visual Studio, Claude Code, and other MCP-compatible agents.
One tool call. A washing machine comes back with named drum, door, control
panel, and hose connectors — separately editable, not fused into a blob.
Quickstart
Claude Code:
- Run
claude mcp add nova3d -- uvx nova3d-mcp
- In Claude, call
nova3d_login
- Complete the Nova3D browser sign-in flow
- Then call
nova3d_status
Other MCP clients:
Why Nova3D
Every major AI 3D generator today produces mesh blobs — a single fused
object that looks plausible in a render and collapses the moment you try to
edit, rig, or pipeline it.
Nova3D is different. Instead of diffusion → mesh, it runs:
prompt / image
↓
LLM writes Blender Python construction code
↓
headless Blender executes + validates + repairs
↓
structured GLB — named parts, intact hierarchy, real joints
The result is a 3D asset that survives contact with real workflows: game
engines, configurators, robotics simulations, AR scenes. Parts have names.
Hierarchy is intact. Joints are real. You can change one component without
regenerating everything.
Supported clients
| Client | Status | Install path | Preview path |
|---|
| Codex | Supported | codex mcp add or Codex MCP config | Browser conversation_url |
| Cursor | Supported | .cursor/mcp.json or ~/.cursor/mcp.json | Browser conversation_url |
| VS Code | Supported | .vscode/mcp.json, MCP: Add Server, or code --add-mcp | Browser conversation_url |
| Visual Studio | Supported | .mcp.json or Visual Studio MCP UI | Browser conversation_url |
| Claude Code | Supported | claude mcp add | Browser conversation_url |
Nova3D runs from your MCP client, but model inspection happens through the
hosted browser viewer returned as conversation_url. This repository does not
currently ship an embedded IDE-native 3D viewport.
Install
Add the MCP server in your client first. This only registers the server. It
does not complete Nova3D account onboarding yet.
Codex
codex mcp add nova3d -- uvx nova3d-mcp
Codex also supports MCP configuration through ~/.codex/config.toml. If you
prefer config files over the CLI, use Codex's MCP config surface and point it
at the same stdio command: uvx nova3d-mcp.
Claude Code
claude mcp add nova3d -- uvx nova3d-mcp
Cursor
Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for a global
install:
{
"mcpServers": {
"nova3d": {
"command": "uvx",
"args": ["nova3d-mcp"]
}
}
}
VS Code
Option A: add the server from the command line:
code --add-mcp "{\"name\":\"nova3d\",\"command\":\"uvx\",\"args\":[\"nova3d-mcp\"]}"
Option B: create .vscode/mcp.json in your workspace:
{
"servers": {
"nova3d": {
"command": "uvx",
"args": ["nova3d-mcp"]
}
}
}
You can also use MCP: Add Server from the Command Palette.
Visual Studio
Create <SOLUTIONDIR>/.mcp.json or %USERPROFILE%/.mcp.json:
{
"servers": {
"nova3d": {
"command": "uvx",
"args": ["nova3d-mcp"]
}
}
}
You can also add the server from the Visual Studio MCP UI by providing the
stdio command uvx with args ["nova3d-mcp"].
After the server is installed in any client, the next step is to call
nova3d_login or nova3d_setup from inside that client. Installation alone
does not complete Nova3D onboarding.
First Run
After installing the MCP server in any client:
- Call
nova3d_login
- Complete the Nova3D sign-in flow in the browser tab that opens
- Call
nova3d_status
- If
next_action == "purchase_credits", follow the returned purchase link
- When
authenticated: true and generation_ready: true, start using generate_3d
Important:
- Installing the MCP server and completing Nova3D sign-in are separate steps.
nova3d_login opens a browser tab and may return login_pending_confirmation: true
while local MCP session setup is still being confirmed.
- If browser sign-in finishes but login completion is ambiguous, call
nova3d_status before retrying or considering manual fallback.
NOVA3D_TOKEN is an advanced/manual fallback only for environments where
browser/loopback auth is unavailable.
For AI Assistants
If you are helping a user set up Nova3D MCP:
- Ensure the
nova3d MCP server is installed in the client
- Call
nova3d_login
- Tell the user a browser tab will open and they must complete sign-in there
- After browser sign-in, call
nova3d_status
- If
next_action == "purchase_credits", direct the user to the returned URL
- Proceed to
generate_3d only when authenticated: true and generation_ready: true
- Only suggest manual
NOVA3D_TOKEN setup if browser/loopback auth is unavailable
Onboarding Decision Tree
- If
nova3d_login returns login_pending_confirmation: true
- complete the browser sign-in flow
- then call
nova3d_status
- If
nova3d_status.next_action == "sign_in"
- If
nova3d_status.next_action == "session_expired"
- If
nova3d_status.next_action == "purchase_credits"
- follow the returned purchase URL
- If
nova3d_status.next_action == null and generation_ready == true
Local install
If you prefer to install from source instead of uvx, clone the repository and
install the package locally:
git clone https://github.com/RareSense/nova3d-mcp.git
cd nova3d-mcp
python3.10 -m venv .venv && source .venv/bin/activate
pip install .
Then replace uvx nova3d-mcp in the client examples above with the local
nova3d-mcp executable from your environment.
Typical workflow
Once onboarding is complete, pass a prompt like this to your AI agent:
Generate a vending machine with separate door, glass panel, coin slot,
button grid, frame, and interior shelving.
The agent calls generate_3d. You get back:
{
"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 — your editing session in the Nova3D app, with the generated model and edit history already hydrated. All subsequent regenerate_part, add_part, and articulate_model calls on this asset link back to the same session.
Configuration notes
conversation_url is the standard supported way to inspect generated assets — it opens your fully hydrated editing session in the Nova3D app.
- Preferred onboarding is browser sign-in through
nova3d_login, then nova3d_status to confirm credits/readiness.
nova3d_login opens a browser tab and starts local MCP session setup through a loopback callback.
nova3d_status is the canonical follow-up check for authentication, credits, and readiness.
- Keep secrets out of checked-in workspace config when possible. Prefer
per-user configuration files or client-managed environment variables.
- If your editor supports source-controlled MCP config, commit the server entry
and inject
NOVA3D_TOKEN per-user only for the advanced/manual fallback path.
Troubleshooting
| Problem | What to check |
|---|
| Prompted to sign in before generation | Call nova3d_login, then re-check with nova3d_status |
nova3d_login returns login_pending_confirmation: true | Finish the browser sign-in step, then call nova3d_status |
Browser sign-in finished but nova3d_login did not confirm completion | Call nova3d_status now. If it still shows not signed in, retry nova3d_login |
| Told that credits are required | Follow the purchase link returned by nova3d_status |
| Auth failure on startup | Sign in again with nova3d_login, or confirm the manual key at https://app.nova3d.xyz/api-key |
uvx not found | Install uv or use a local nova3d-mcp executable from a virtualenv |
| No 3D preview inside the editor | Open the returned conversation_url in the browser; that is the supported preview path |
generate_3d
Generate a structured 3D asset from text (and optional reference image).
Initial generation runs through Nova3D's paid GraphFlow v2 workflow. This MCP
server does not expose BYOK/provider-key generation.
| Parameter | Type | Required | Description |
|---|
prompt | string | ✓ | Asset description. Be specific about parts. |
model | string | | Paid routing preset: "gemini" (default) · "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5" |
image_base64 | string | | Reference image as plain base64; the server converts it to the v2 image_artifact data-URL format |
image_mime | string | | e.g. "image/jpeg" |
Returns: glb_url, conversation_url, parts, joint_count, code_artifact, model_artifact, workflow_id. Pass code_artifact to any edit tool. Open conversation_url to see the full edit history for this asset in the Nova3D app.
regenerate_part
Regenerate one named part without rebuilding the whole asset.
| Parameter | Type | Required | Description |
|---|
code_artifact | object | ✓ | From prior generate_3d result |
part_type | string | ✓ | Part name e.g. "door", "handle" |
description | string | ✓ | What the new part should look like |
model | string | | "gemini" (default) · "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5" |
Finding part names: Open the conversation_url from your generation and
inspect the model viewer — each mesh is labeled. Use that exact name as
part_type.
add_part
Add a new component to an existing asset.
| Parameter | Type | Required | Description |
|---|
code_artifact | object | ✓ | From prior generation result |
description | string | ✓ | Description of the new part and where it goes |
model | string | | "gemini" (default) · "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5" |
articulate_model
Add joints, hinges, or rotational articulation to an existing asset.
| Parameter | Type | Required | Description |
|---|
code_artifact | object | ✓ | From prior generation result |
articulation_request | string | ✓ | What should move and how |
model_url | string | | glb_url from prior generation. Provide this or model_artifact. |
model_artifact | object | | model_artifact from prior generation. Provide this or model_url. |
model | string | | "gemini" (default) · "claude-sonnet" · "claude-opus" · "claude-opus-latest" · "gpt-5.5" |
selected_meshes | list | | Specific mesh names to articulate |
get_generation_status
Check the status of a running workflow by ID.
| Parameter | Type | Required | Description |
|---|
workflow_id | string | ✓ | From any prior generation tool |
nova3d_login
Start the preferred browser-based Nova3D sign-in flow and store a local MCP session.
This opens a browser tab. If the browser flow finishes but local completion is
ambiguous, call nova3d_status before using manual token fallback.
nova3d_status
Return the canonical Nova3D onboarding/readiness state, including identity,
credits, generation readiness, and the next recommended action.
nova3d_logout
Clear the locally stored MCP session. This does not remove an advanced/manual
NOVA3D_TOKEN from your MCP config.
Typical workflow
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
All edit tools accept the code_artifact from any prior result and return an updated one. Always pass the most recent code_artifact forward — it carries the session state that links your edits together.
Model reference
model value | Provider | Notes |
|---|
"gemini" (default) | Google Gemini | Recommended for spatial reasoning |
"claude-sonnet" | Anthropic | Strong reasoning |
"claude-opus" | Anthropic | Most capable Anthropic model |
"claude-opus-latest" | Anthropic | Latest Opus version |
"gpt-5.5" | OpenAI | Latest GPT model |
Environment variables
| Variable | Required | Description |
|---|
NOVA3D_TOKEN | | Advanced/manual fallback API key from https://app.nova3d.xyz/api-key |
NOVA3D_API_URL | | Override API base URL (default: https://nova3d.xyz/api) |
NOVA3D_APP_URL | | Override app URL for conversation links (default: https://app.nova3d.xyz) |
How it differs from blender-mcp
blender-mcp (21.9k ★) gives AI
agents a remote control for a locally running Blender instance. It requires
Blender installed, produces unstructured output, and inherits all the bpy
hallucination problems of raw LLM → Blender code generation.
nova3d-mcp is different in kind:
| blender-mcp | nova3d-mcp |
|---|
| Blender required | Yes | No |
| Output | Unstructured scene | Named, hierarchical GLB |
| Validation | None | Server-side repair loop |
| Part awareness | No | Yes — named, addressable |
| Joints | Manual scripting | First-class output |
| Hosted backend | No | Yes |
Contributing
Issues, PRs, and workflow feedback welcome.
github.com/RareSense/nova3d-mcp
Community Discord: discord.gg/QEH8mzcwdR
License
MIT — see LICENSE