Nova3D

[!WARNING] Moved: Development continues in the Nova3D monorepo: https://github.com/RareSense/Nova3D/tree/main/mcp

nova3d-mcp

<!-- mcp-name: io.github.RareSense/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:

1. Run claude mcp add nova3d -- uvx nova3d-mcp
2. In Claude, call nova3d_login
3. Complete the Nova3D browser sign-in flow
4. Then call nova3d_status

Other MCP clients:

• See Install for client-specific setup
• Then follow the shared First Run steps

---

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:

1. Call nova3d_login
2. Complete the Nova3D sign-in flow in the browser tab that opens
3. Call nova3d_status
4. If next_action == "purchase_credits", follow the returned purchase link
5. 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:

1. Ensure the nova3d MCP server is installed in the client
2. Call nova3d_login
3. Tell the user a browser tab will open and they must complete sign-in there
4. After browser sign-in, call nova3d_status
5. If next_action == "purchase_credits", direct the user to the returned URL
6. Proceed to generate_3d only when authenticated: true and generation_ready: true
7. 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"
• call nova3d_login
• If nova3d_status.next_action == "session_expired"
• call nova3d_login again
• If nova3d_status.next_action == "purchase_credits"
• follow the returned purchase URL
• If nova3d_status.next_action == null and generation_ready == true
• proceed to generate_3d

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 |

---

Tools

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