{
  "markdown": "> [!WARNING]\n> **Moved:** Development continues in the Nova3D monorepo:\n> https://github.com/RareSense/Nova3D/tree/main/mcp\n\n# nova3d-mcp\n\n<!-- mcp-name: io.github.RareSense/nova3d-mcp -->\n\n**Structured, part-aware 3D generation for AI agents.**\n\nnova3d-mcp is an [MCP](https://modelcontextprotocol.io) server that exposes\n[Nova3D](https://nova3d.xyz)'s generation pipeline as a callable tool inside\nCodex, Cursor, VS Code, Visual Studio, Claude Code, and other MCP-compatible agents.\n\nOne tool call. A washing machine comes back with named drum, door, control\npanel, and hose connectors — separately editable, not fused into a blob.\n\n---\n\n## Quickstart\n\nClaude Code:\n\n1. Run `claude mcp add nova3d -- uvx nova3d-mcp`\n2. In Claude, call `nova3d_login`\n3. Complete the Nova3D browser sign-in flow\n4. Then call `nova3d_status`\n\nOther MCP clients:\n\n- See [Install](#install) for client-specific setup\n- Then follow the shared [First Run](#first-run) steps\n\n---\n\n## Why Nova3D\n\nEvery major AI 3D generator today produces **mesh blobs** — a single fused\nobject that looks plausible in a render and collapses the moment you try to\nedit, rig, or pipeline it.\n\nNova3D is different. Instead of diffusion → mesh, it runs:\n\n```\nprompt / image\n      ↓\nLLM writes Blender Python construction code\n      ↓\nheadless Blender executes + validates + repairs\n      ↓\nstructured GLB — named parts, intact hierarchy, real joints\n```\n\nThe result is a 3D asset that **survives contact with real workflows**: game\nengines, configurators, robotics simulations, AR scenes. Parts have names.\nHierarchy is intact. Joints are real. You can change one component without\nregenerating everything.\n\n---\n\n## Supported clients\n\n| Client | Status | Install path | Preview path |\n|---|---|---|---|\n| Codex | Supported | `codex mcp add` or Codex MCP config | Browser `conversation_url` |\n| Cursor | Supported | `.cursor/mcp.json` or `~/.cursor/mcp.json` | Browser `conversation_url` |\n| VS Code | Supported | `.vscode/mcp.json`, MCP: Add Server, or `code --add-mcp` | Browser `conversation_url` |\n| Visual Studio | Supported | `.mcp.json` or Visual Studio MCP UI | Browser `conversation_url` |\n| Claude Code | Supported | `claude mcp add` | Browser `conversation_url` |\n\nNova3D runs from your MCP client, but model inspection happens through the\nhosted browser viewer returned as `conversation_url`. This repository does not\ncurrently ship an embedded IDE-native 3D viewport.\n\n---\n\n## Install\n\nAdd the MCP server in your client first. This only registers the server. It\ndoes **not** complete Nova3D account onboarding yet.\n\n#### Codex\n\n```bash\ncodex mcp add nova3d -- uvx nova3d-mcp\n```\n\nCodex also supports MCP configuration through `~/.codex/config.toml`. If you\nprefer config files over the CLI, use Codex's MCP config surface and point it\nat the same stdio command: `uvx nova3d-mcp`.\n\n#### Claude Code\n\n```bash\nclaude mcp add nova3d -- uvx nova3d-mcp\n```\n\n#### Cursor\n\nCreate `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for a global\ninstall:\n\n```json\n{\n  \"mcpServers\": {\n    \"nova3d\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nova3d-mcp\"]\n    }\n  }\n}\n```\n\n#### VS Code\n\nOption A: add the server from the command line:\n\n```bash\ncode --add-mcp \"{\\\"name\\\":\\\"nova3d\\\",\\\"command\\\":\\\"uvx\\\",\\\"args\\\":[\\\"nova3d-mcp\\\"]}\"\n```\n\nOption B: create `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"nova3d\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nova3d-mcp\"]\n    }\n  }\n}\n```\n\nYou can also use `MCP: Add Server` from the Command Palette.\n\n#### Visual Studio\n\nCreate `<SOLUTIONDIR>/.mcp.json` or `%USERPROFILE%/.mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"nova3d\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nova3d-mcp\"]\n    }\n  }\n}\n```\n\nYou can also add the server from the Visual Studio MCP UI by providing the\nstdio command `uvx` with args `[\"nova3d-mcp\"]`.\n\nAfter the server is installed in any client, the next step is to call\n`nova3d_login` or `nova3d_setup` from inside that client. Installation alone\ndoes not complete Nova3D onboarding.\n\n## First Run\n\nAfter installing the MCP server in any client:\n\n1. Call `nova3d_login`\n2. Complete the Nova3D sign-in flow in the browser tab that opens\n3. Call `nova3d_status`\n4. If `next_action == \"purchase_credits\"`, follow the returned purchase link\n5. When `authenticated: true` and `generation_ready: true`, start using `generate_3d`\n\nImportant:\n\n- Installing the MCP server and completing Nova3D sign-in are separate steps.\n- `nova3d_login` opens a browser tab and may return `login_pending_confirmation: true`\n  while local MCP session setup is still being confirmed.\n- If browser sign-in finishes but login completion is ambiguous, call\n  `nova3d_status` before retrying or considering manual fallback.\n- `NOVA3D_TOKEN` is an advanced/manual fallback only for environments where\n  browser/loopback auth is unavailable.\n\n## For AI Assistants\n\nIf you are helping a user set up Nova3D MCP:\n\n1. Ensure the `nova3d` MCP server is installed in the client\n2. Call `nova3d_login`\n3. Tell the user a browser tab will open and they must complete sign-in there\n4. After browser sign-in, call `nova3d_status`\n5. If `next_action == \"purchase_credits\"`, direct the user to the returned URL\n6. Proceed to `generate_3d` only when `authenticated: true` and `generation_ready: true`\n7. Only suggest manual `NOVA3D_TOKEN` setup if browser/loopback auth is unavailable\n\n## Onboarding Decision Tree\n\n- If `nova3d_login` returns `login_pending_confirmation: true`\n  - complete the browser sign-in flow\n  - then call `nova3d_status`\n- If `nova3d_status.next_action == \"sign_in\"`\n  - call `nova3d_login`\n- If `nova3d_status.next_action == \"session_expired\"`\n  - call `nova3d_login` again\n- If `nova3d_status.next_action == \"purchase_credits\"`\n  - follow the returned purchase URL\n- If `nova3d_status.next_action == null` and `generation_ready == true`\n  - proceed to `generate_3d`\n\n## Local install\n\nIf you prefer to install from source instead of `uvx`, clone the repository and\ninstall the package locally:\n\n```bash\ngit clone https://github.com/RareSense/nova3d-mcp.git\ncd nova3d-mcp\npython3.10 -m venv .venv && source .venv/bin/activate\npip install .\n```\n\nThen replace `uvx nova3d-mcp` in the client examples above with the local\n`nova3d-mcp` executable from your environment.\n\n## Typical workflow\n\nOnce onboarding is complete, pass a prompt like this to your AI agent:\n\n```\nGenerate a vending machine with separate door, glass panel, coin slot,\nbutton grid, frame, and interior shelving.\n```\n\nThe agent calls `generate_3d`. You get back:\n\n```json\n{\n  \"glb_url\": \"https://nova3d.xyz/assets/abc123.glb\",\n  \"conversation_url\": \"https://app.nova3d.xyz/chat/conv-...\",\n  \"parts\": [\"door\", \"glass_panel\", \"coin_slot\", \"button_grid\", \"frame\", \"shelf_1\", \"shelf_2\"],\n  \"joint_count\": 1,\n  \"code_artifact\": { ... },\n  \"workflow_id\": \"state-...\"\n}\n```\n\n- **`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.\n\n---\n\n## Configuration notes\n\n- `conversation_url` is the standard supported way to inspect generated assets — it opens your fully hydrated editing session in the Nova3D app.\n- Preferred onboarding is browser sign-in through `nova3d_login`, then `nova3d_status` to confirm credits/readiness.\n- `nova3d_login` opens a browser tab and starts local MCP session setup through a loopback callback.\n- `nova3d_status` is the canonical follow-up check for authentication, credits, and readiness.\n- Keep secrets out of checked-in workspace config when possible. Prefer\n  per-user configuration files or client-managed environment variables.\n- If your editor supports source-controlled MCP config, commit the server entry\n  and inject `NOVA3D_TOKEN` per-user only for the advanced/manual fallback path.\n\n---\n\n## Troubleshooting\n\n| Problem | What to check |\n|---|---|\n| Prompted to sign in before generation | Call `nova3d_login`, then re-check with `nova3d_status` |\n| `nova3d_login` returns `login_pending_confirmation: true` | Finish the browser sign-in step, then call `nova3d_status` |\n| 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` |\n| Told that credits are required | Follow the purchase link returned by `nova3d_status` |\n| Auth failure on startup | Sign in again with `nova3d_login`, or confirm the manual key at https://app.nova3d.xyz/api-key |\n| `uvx` not found | Install `uv` or use a local `nova3d-mcp` executable from a virtualenv |\n| No 3D preview inside the editor | Open the returned `conversation_url` in the browser; that is the supported preview path |\n\n---\n\n## Tools\n\n### `generate_3d`\n\nGenerate a structured 3D asset from text (and optional reference image).\nInitial generation runs through Nova3D's paid GraphFlow v2 workflow. This MCP\nserver does not expose BYOK/provider-key generation.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `prompt` | string | ✓ | Asset description. Be specific about parts. |\n| `model` | string | | Paid routing preset: `\"gemini\"` (default) · `\"claude-sonnet\"` · `\"claude-opus\"` · `\"claude-opus-latest\"` · `\"gpt-5.5\"` |\n| `image_base64` | string | | Reference image as plain base64; the server converts it to the v2 `image_artifact` data-URL format |\n| `image_mime` | string | | e.g. `\"image/jpeg\"` |\n\n**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.\n\n---\n\n### `regenerate_part`\n\nRegenerate one named part without rebuilding the whole asset.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `code_artifact` | object | ✓ | From prior `generate_3d` result |\n| `part_type` | string | ✓ | Part name e.g. `\"door\"`, `\"handle\"` |\n| `description` | string | ✓ | What the new part should look like |\n| `model` | string | | `\"gemini\"` (default) · `\"claude-sonnet\"` · `\"claude-opus\"` · `\"claude-opus-latest\"` · `\"gpt-5.5\"` |\n\n**Finding part names:** Open the `conversation_url` from your generation and\ninspect the model viewer — each mesh is labeled. Use that exact name as\n`part_type`.\n\n---\n\n### `add_part`\n\nAdd a new component to an existing asset.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `code_artifact` | object | ✓ | From prior generation result |\n| `description` | string | ✓ | Description of the new part and where it goes |\n| `model` | string | | `\"gemini\"` (default) · `\"claude-sonnet\"` · `\"claude-opus\"` · `\"claude-opus-latest\"` · `\"gpt-5.5\"` |\n\n---\n\n### `articulate_model`\n\nAdd joints, hinges, or rotational articulation to an existing asset.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `code_artifact` | object | ✓ | From prior generation result |\n| `articulation_request` | string | ✓ | What should move and how |\n| `model_url` | string | | `glb_url` from prior generation. Provide this or `model_artifact`. |\n| `model_artifact` | object | | `model_artifact` from prior generation. Provide this or `model_url`. |\n| `model` | string | | `\"gemini\"` (default) · `\"claude-sonnet\"` · `\"claude-opus\"` · `\"claude-opus-latest\"` · `\"gpt-5.5\"` |\n| `selected_meshes` | list | | Specific mesh names to articulate |\n\n---\n\n### `get_generation_status`\n\nCheck the status of a running workflow by ID.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `workflow_id` | string | ✓ | From any prior generation tool |\n\n---\n\n### `nova3d_login`\n\nStart the preferred browser-based Nova3D sign-in flow and store a local MCP session.\nThis opens a browser tab. If the browser flow finishes but local completion is\nambiguous, call `nova3d_status` before using manual token fallback.\n\n---\n\n### `nova3d_status`\n\nReturn the canonical Nova3D onboarding/readiness state, including identity,\ncredits, generation readiness, and the next recommended action.\n\n---\n\n### `nova3d_logout`\n\nClear the locally stored MCP session. This does not remove an advanced/manual\n`NOVA3D_TOKEN` from your MCP config.\n\n---\n\n## Typical workflow\n\n```\n1. generate_3d(\"robot dog with four legs, head, torso, and tail\")\n   → glb_url, conversation_url, parts, code_artifact\n\n2. Open conversation_url in browser\n   → see named parts, identify what needs changing\n\n3. regenerate_part(code_artifact, part_type=\"head\", description=\"...\")\n   → updated glb_url, same conversation_url\n\n4. add_part(code_artifact, description=\"a wagging tail with three segments\")\n   → updated glb_url, parts list now includes new tail segments\n\n5. articulate_model(code_artifact, model_url, \"make legs rotate at hip joints\")\n   → glb_url with working joints\n```\n\nAll 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.\n\n---\n\n## Model reference\n\n| `model` value | Provider | Notes |\n|---|---|---|\n| `\"gemini\"` *(default)* | Google Gemini | Recommended for spatial reasoning |\n| `\"claude-sonnet\"` | Anthropic | Strong reasoning |\n| `\"claude-opus\"` | Anthropic | Most capable Anthropic model |\n| `\"claude-opus-latest\"` | Anthropic | Latest Opus version |\n| `\"gpt-5.5\"` | OpenAI | Latest GPT model |\n\n---\n\n## Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `NOVA3D_TOKEN` | | Advanced/manual fallback API key from https://app.nova3d.xyz/api-key |\n| `NOVA3D_API_URL` | | Override API base URL (default: `https://nova3d.xyz/api`) |\n| `NOVA3D_APP_URL` | | Override app URL for conversation links (default: `https://app.nova3d.xyz`) |\n\n---\n\n## How it differs from blender-mcp\n\n[blender-mcp](https://github.com/ahujasid/blender-mcp) (21.9k ★) gives AI\nagents a remote control for a **locally running Blender instance**. It requires\nBlender installed, produces unstructured output, and inherits all the bpy\nhallucination problems of raw LLM → Blender code generation.\n\nnova3d-mcp is different in kind:\n\n| | blender-mcp | nova3d-mcp |\n|---|---|---|\n| Blender required | Yes | No |\n| Output | Unstructured scene | Named, hierarchical GLB |\n| Validation | None | Server-side repair loop |\n| Part awareness | No | Yes — named, addressable |\n| Joints | Manual scripting | First-class output |\n| Hosted backend | No | Yes |\n\n---\n\n## Contributing\n\nIssues, PRs, and workflow feedback welcome.\n[github.com/RareSense/nova3d-mcp](https://github.com/RareSense/nova3d-mcp)\n\nCommunity Discord: [discord.gg/QEH8mzcwdR](https://discord.gg/QEH8mzcwdR)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 14729,
  "sha": "a0bcf119203614de97aab08c0c2ebb5f7ebee745cb1b9a209896013a8d6b99b2",
  "repo_slug": "raresense/nova3d-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_raresense_nova3d_mcp_a0d233d9/readme"
}