nova3d-mcp

Warning

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

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:

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:

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"
- 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

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.github/workflows		.github/workflows
nova3d_mcp		nova3d_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
llms.txt		llms.txt
pyproject.toml		pyproject.toml
server.json		server.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

nova3d-mcp

Quickstart

Why Nova3D

Supported clients

Install

Codex

Claude Code

Cursor

VS Code

Visual Studio

First Run

For AI Assistants

Onboarding Decision Tree

Local install

Typical workflow

Configuration notes

Troubleshooting

Tools

generate_3d

regenerate_part

add_part

articulate_model

get_generation_status

nova3d_login

nova3d_status

nova3d_logout

Typical workflow

Model reference

Environment variables

How it differs from blender-mcp

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`generate_3d`

`regenerate_part`

`add_part`

`articulate_model`

`get_generation_status`

`nova3d_login`

`nova3d_status`

`nova3d_logout`

Packages