MeshVault

A professional, local web-based tool for rapidly browsing, previewing, and managing 3D assets across your filesystem — including assets inside archives.

Three ways to use it:

Supported Formats

Older FBX files (version < 7000) are auto-converted to OBJ by a built-in zero-dependency parser. .usdz is import-only.

Features

Quick Start

git clone https://github.com/lpalbou/meshvault.git
cd meshvault
poetry install --no-root
poetry run meshvault

Open http://localhost:8420 · Also: pip install meshvault or npx meshvault

MeshVault binds to 127.0.0.1 and requires a session token on every /api/* request. By default it can browse your whole filesystem (opening at your home directory) — the network protections (loopback + token + Host allow-list) are what keep it private. Set MESHVAULT_ROOT=/path[:/path2] to restrict file access to specific directories. Configure MESHVAULT_HOST (bind host) and MESHVAULT_TOKEN as needed. Opening the URL on the same machine authenticates automatically; other devices need the token from the launch banner. See API Reference.

Control MeshVault with AI agents

MeshVault is built to be driven by agents, not just humans. Four entry points, from lightest to most integrated:

1. Self-describing JSON control API — the viewer exposes one entry point, execute({action, params}), with ~70 discoverable commands (listCommands()), plus describe_scene: a structured text snapshot (inventory, size, materials, geometry-QA issues, current view) so a text-only agent can reason without screenshots. Agent-ready reference served at /llms.txt and /llms-full.txt.
2. MCP server — meshvault-mcp lets Claude Desktop / Claude Code / Cursor drive a headless viewer natively through 13 tools: load a model by URL or local file path (multi-file OBJ/FBX assets load textured), compose multi-object scenes (add: true + placement commands, persisted as .mvscene via save_scene/load_scene), create and modify content — primitives, sculpting brushes, texture painting, screenshot-coordinate picking (the agent hand-eye loop) — describe it, run any viewer command, and get PNG screenshots back as image content (best_view: true gives a one-call hero shot; preset: "studio" pins lighting so renders are comparable across sessions). With the app running, co-review works both ways: open_in_app pushes the agent's model + camera into the human's browser tab, and get_app_state reads back what the human is looking at. Setup: docs/mcp.md.
3. Headless REST screenshot — GET /api/screenshot?path=…&best_view=true returns a PNG over plain authenticated HTTP (same reproducible presets) — agent loops with nothing but curl. Reference: docs/api.md.
4. Embeddable standalone viewer — meshvault-viewer.js is a server-less ES-module bundle (Three.js included, offline, compressed-glTF decoders bundled) exposing the same control API for your own pages or agent harnesses.

Typical agent flow: load → describe_scene → find_best_view (finds the model's semantic front and uprights it) → set_render_mode / set_clip to inspect → screenshot.

Documentation

• Getting Started — Installation, UI overview, complete feature guide
• Architecture — System design, components, rendering pipeline
• API Reference — REST API (24 routes, incl. headless GET /api/screenshot and scene save/load)
• MCP Server — Drive the viewer from Claude/Cursor via Model Context Protocol
• FAQ — Troubleshooting and tips

License

MIT — © 2026 Laurent-Philippe Albou — contact@abstractcore.ai