Skip to main content
Glama

Cognito-3D-mcp

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 SF3D

Runtimes 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

codex_3d_models_hunyuan_mv

Multiview 3D

Single-image SF3D and SPAR3D generation or backend comparisons

codex_3d_models / codex_3d_models_spar3d

Single-image 3D

Matched front/back reconstruction with fusion and QA

codex_3d_models_trellis

Bidirectional 3D

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.ps1

MCP 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 tools
cancel_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

    C2.9/5.0

    Scored across 19 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers