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

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

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.

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.

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.

articulate_model

Add joints, hinges, or rotational articulation to an existing asset.

get_generation_status

Check the status of a running workflow by ID.

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

Environment variables

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:

Contributing

Issues, PRs, and workflow feedback welcome. github.com/RareSense/nova3d-mcp

Community Discord: discord.gg/QEH8mzcwdR

License

MIT — see LICENSE