# Vectreal

An MCP server for Claude Code, Cursor and other agents that uploads GLB models to Vectreal, manages scene parameters, compresses and publishes them, then generates embed code for websites.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 27 repo stars
- Author: Vectreal
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Vectreal/vectreal-platform/tree/HEAD/packages/cli
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/vectreal

## What it does

The server runs via `@vctrl/cli` and exposes tools for working with 3D scenes. It uploads local GLB files as drafts, reads model data (size, meshes, materials, animation clips), adjusts environment and camera settings, compresses scenes (Draco, KTX2) during publication, and delivers embeddable code snippets.

Requires login through `vectreal login` — the session lives in OS keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux), or in `~/.config/vectreal/credentials.json` on headless systems without Secret Service. Links to a project in the current directory via `vectreal init`; tools use that project by default, or you can pass `--project` to switch. Documentation access via `search_docs` and `read_doc` works without authentication. All other operations — listing projects, creating scenes, publishing — need an active session.

Tools that need a project ID fall back to the one `vectreal init` linked; the server finds it in `CLAUDE_PROJECT_DIR` when set by the agent, otherwise in the launch directory.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add vectreal -- npx -y @vctrl/cli
```

### Codex

**Platform CLI**
```bash
codex mcp add cli -- npx -y @vctrl/cli
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "cli": {
            "command": "npx",
            "args": [
                "-y",
                "@vctrl/cli"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "cli": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@vctrl/cli"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add cli npx -y @vctrl/cli
```

## When to use it
- upload a 3D model as a draft and publish it to the server
- embed a published 3D scene on a website with custom settings
- inspect the mesh and material structure of a GLB file before uploading
- adjust 3D scene parameters — lighting, camera, shadows — from the agent
- publish multiple models in a single project and share embed links

## Example prompts
- Upload `character.glb` as a new scene in the current project
- Compress and publish the scene, then give me the embed code
- Show me the meshes and materials in `scene.glb` without uploading it

## Similar
- [three.ws Assistant Widget](https://affpapa.org/en/nevibecode/mcp/threews-assistant-widget.md) — MCP server · ★ 284 repo stars
- [fal-regenerate-3d](https://affpapa.org/en/nevibecode/skills/fal-regenerate-3d.md) — skill · 442 installs
- [three.ws Avatars](https://affpapa.org/en/nevibecode/mcp/threews-avatars.md) — MCP server · ★ 284 repo stars
- [3DAssets.dev](https://affpapa.org/en/nevibecode/mcp/3dassetsdev.md) — MCP server · ★ 8 repo stars
- [Lumen](https://affpapa.org/en/nevibecode/mcp/qompassai-lumen.md) — MCP server
- [texture-state-animation](https://affpapa.org/en/nevibecode/skills/texture-state-animation.md) — skill · 1300 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
