Cognito-3D-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cognito-3D-MCP Turn the reference images into a 3D GLB"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cognito-3D-mcp

Local image-to-3D tools for MCP clients. Create textured GLBs, inspect them in a local 3D viewer, repair geometry, and export assets through durable, reviewed jobs. This repository ships the MCP integration, Windows setup scripts, tests, and the agent skills needed to drive the workflows.
3D only: there is no sprite rig, spritesheet generator, or 2D editor. Reference PNG preparation is part of the 3D reconstruction pipeline.
Install on Windows
Download and extract the repository ZIP, then double-click Install.cmd
and choose a 3D engine from its guided menu. The installer prepares an isolated
runtime, downloads the selected engine's
models, installs support tools, and configures Codex and the bundled skills.
It checks each command and stops when a prerequisite or download fails.
Run it again after correcting the reported issue.
The default engine is Hunyuan3D-2mv. Its licence excludes the EU, UK and South Korea. The installer requires acknowledgement of the upstream terms before downloading it. Users need suitable rights for the engine they select; the MIT licence of this integration does not change model terms. See third-party notices.
Generation requires a compatible NVIDIA GPU/driver, Python 3.11, Visual Studio 2022 C++ Build Tools, and the matching CUDA toolkit for native extension builds. The installer reports missing prerequisites and can bootstrap supported tools through Windows Package Manager. Allow at least 45 GB free for the Hunyuan runtime/model install; additional environments and generated assets need more. Windows is the supported generation setup. CPU tests and the lightweight MCP package also run on Linux; a Linux GPU installer is not provided.
Installation is one launcher with guided prerequisite/licence steps, rather than a promise that drivers, model access approvals, or hardware can be installed without user involvement. Large model downloads can take substantial time.
Advanced installation and a preview with no downloads or configuration writes:
.\install.ps1 -DryRun
.\install.ps1 -Backend Hunyuan
.\install.ps1 -Backend SPAR3D
.\install.ps1 -Backend SF3DRuntimes and model caches default to %LOCALAPPDATA%\Cognito-3D-mcp.
The installer also defaults outputs to %LOCALAPPDATA%\Cognito-3D-mcp\outputs.
Use installer parameters or .env for alternate locations. The
example environment contains no account-specific paths or credentials.
Stability AI backends require access to gated Hugging Face models. Accept the model terms with your own account. The installer reuses existing credentials or guides you through local Hugging Face authentication before downloading weights. Do not put a token in chat or source control. The installer preserves existing MCP configuration and skill directories and reports conflicts for manual review. Restart Codex after installing or updating MCP servers and skills.
Related MCP server: Hunyuan-mcp-webui
Choose a workflow
Workflow | Registered server | Agent skill |
Named-view Hunyuan batches; repair, remesh, Paint, bake and inspect profiles |
| |
Single-image SF3D and SPAR3D generation or backend comparisons |
| |
Matched front/back reconstruction with fusion and QA |
|
For example, ask the connected agent: “Use Cognito-3D-mcp to create a textured
3D asset from these reference images.” The agent checks server_status, prepares
consistent images beneath an allowed input root, runs serial work, inspects the
quality evidence, and returns accepted GLBs. Text descriptions need an
image-generation capability in the MCP client; this server does not include an
image generator or make LLM API calls.
The Hunyuan batch workflow registers all assets, approves reference cutouts, generates shapes, repairs and reviews them, independently remeshes three output profiles, paints the full-game profile, and bakes that appearance to the lower profiles. Worker processes and GPU leases are serial. Passing machine gates and agent reviews are required before later stages or delivery.
The queue opens a loopback dashboard with progress, previews, quality reports, and an interactive model viewer. Viewer modules are shipped locally. Failed attempts and completed checkpoints remain available for repair and restart.
Run and connect other clients
Codex starts the configured servers automatically when it connects. Run.cmd
starts the installed server manually; it waits for an MCP client on STDIO.
To select a particular installed engine, pass -Backend SPAR3D (or another
engine name).
.\scripts\run-hunyuan-mv-server.ps1MCP uses STDIO, so a terminal run waits for a client protocol session. Other MCP hosts can start the same launcher with an absolute repository path:
{
"mcpServers": {
"cognito-3d": {
"command": "powershell.exe",
"args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\Cognito-3D-mcp\\scripts\\run-hunyuan-mv-server.ps1"]
}
}
}That execution-policy setting applies to the launched process. A non-Codex host
must supply the same workflow instructions or import the relevant skills/
content. Compatibility server names, the Python namespace codex_3d_mcp, and
CODEX_* variables remain stable despite the product rebrand.
Documentation and development
The source ZIP contains the installer and skills. A Python wheel is the lightweight integration package; heavy model runtimes are installed separately. Automated checks verify source files, skill references, wheel browser assets, HTTP access, job lifecycle, and CPU quality logic. Fresh-machine GPU installation and real generation remain separate hardware checks; see release verification.
Licensing
Original integration code and workflow skills use the MIT licence. External engines, model weights, and native tools retain their own terms. Cognito-3D-mcp is maintained independently by Lanc3 and contributors and is not affiliated with or endorsed by Tencent, Stability AI, Microsoft, or OpenAI.
Available Tools
19 toolscancel_generationB
Cancel queued or active work while retaining completed stages.
Inputs: job_id (required).
cleanup_generation_jobB
Explicitly remove job data; preserve final deliverables by default.
Inputs: job_id (required), keep_final.
create_generation_batchB
Queue up to 1000 named assets before generating references; launch queue UI.
Each asset requires prompt and may include name, seed, quality, material_hints, and views {front,back,left,right}. Image creation is performed by the calling Codex agent. Read get_agent_work and continue the agent repair/review loop.
Inputs: name (required), assets (required).
create_shape_repair_attemptA
Queue one typed repair under serial limits; zero source_attempt selects raw shape.
Positive source_attempt selects a retained repair candidate from the current raw shape. A paused batch stays paused. Candidate creation never approves or replaces the master. Mutations require an explicit recipe policy region. Use submission for imported edits.
Inputs: recipe (required), asset_id (required), batch_id (required), diagnosis (required), +5 more.
generate_multiview_3d_modelC
Start a durable Hunyuan3D-2mv job from named canonical views.
Inputs: prompt (required), front_image_path (required), seed, quality, +5 more.
get_agent_workC
Get active-phase image generation, visual review or repair tasks for the Codex agent.
Inputs: limit, batch_id.
get_batch_statusC
Read durable phase, assets, attempts, gates and pending agent actions.
Inputs: batch_id (required).
get_generation_artifactsB
Return paths and SHA-256 hashes for every available job artifact.
Inputs: job_id (required).
get_generation_statusB
Return durable state, stage, progress, warnings, and available artifacts.
Inputs: job_id (required).
get_queue_statusB
Read lightweight queue and resource state without hashing model artifacts.
Inputs: no named parameters.
get_shape_repair_capabilitiesC
Read typed methods and gate policy; discovery is not runtime qualification.
Inputs: no named parameters.
open_generation_queueA
Open the local queue dashboard with previews and pause/resume/cancel controls.
Inputs: no named parameters.
pause_generation_batchB
Pause at the current asset boundary and release the worker before more work starts.
Inputs: batch_id (required).
record_asset_reviewC
Record the agent's inspection of current-attempt evidence; cannot override a failed gate.
Inputs: notes (required), stage (required), attempt (required), approved (required), +3 more.
resume_generationB
Resume an interrupted or repairable failed job from verified outputs.
Inputs: job_id (required).
retry_asset_stageC
Resubmit an agent-repaired stage or rewind its cause, retaining successful other assets.
Inputs: stage (required), changes (required), asset_id (required), batch_id (required), +1 more.
server_statusA
Report Hunyuan runtime, model cache, GPU dependencies, disk, and queue readiness.
Inputs: no named parameters.
submit_asset_referencesC
Prepare immutable RGBA cutouts and run pixel gates; agent visual review is next.
Inputs: asset_id (required), batch_id (required), back_image_path (required), left_image_path (required), +4 more.
submit_shape_repair_candidateB
Stage an allowed-root edited GLB immutably, then run the same repair gates.
Requires recipe.method=import_candidate, an explicit region, and exact candidate/source SHA-256 values. It queues validation and evidence; it does not accept the candidate.
Inputs: recipe (required), asset_id (required), batch_id (required), diagnosis (required), +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Tools have distinct high-level purposes, but the set contains several status/read endpoints (get_batch_status, get_queue_status, get_generation_status, server_status) whose boundaries are subtle. Repair-related tools such as create_shape_repair_attempt, submit_shape_repair_candidate, and retry_asset_stage can also be confused without careful reading.
Names are consistently snake_case and mostly follow a verb_noun pattern (get_*, create_*, submit_*, pause_*, cancel_*). Minor deviations exist, such as server_status being a bare noun phrase instead of get_server_status, and generate_multiview_3d_model being longer but still verb-led.
19 tools falls in the borderline-heavy range (16–25) for a single MCP server. The 3D generation and repair pipeline is genuinely multi-stage, so most tools earn their place, but some status/query endpoints could potentially be consolidated.
The surface covers batch creation, generation, asset references, review, repair, queue control, cancellation, cleanup, artifacts, and agent work—most lifecycle operations are present. A notable gap is an explicit accept/approve operation for repair candidates; the descriptions state candidates are never accepted, leaving that step outside the tool surface.
Maintenance
Related MCP Connectors
Free 3D conversion (FBX, GLB, OBJ, STL, PLY, DAE, USDZ, 3MF) as a remote MCP server. No account.
Free text/image → 3D: generate, rig, avatar-ify, and refine GLB models. No auth, no payment.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- FlicenseAqualityCmaintenanceStandalone MCP server for generating high-fidelity 3D assets from a single image using Pixal3D inference.121-
- FlicenseNot gradedqualityDmaintenanceMCP server for generating 3D assets from images or text using Hunyuan3D on Apple Silicon Mac, with web UI and Codex Image Gen integration.-
- AlicenseAqualityDmaintenanceTurns a single concept image into a game-ready textured 3D model (GLB) locally on Apple Silicon by wrapping Hunyuan3D-MLX, with tools for generation, finishing, preview, and setup diagnostics.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Meshwright, enabling agents to create 3D models from text prompts via a LangGraph pipeline. Supports configurable image providers, background removal, and TRELLIS reconstruction backends.MIT