Content
# Mint Three.js Setup
> Turn your coding agent into a **remote 3D engine** — generate models, worlds,
> PBR materials, asset packs, and audio via [Mint MCP](https://mcp.mint.gg/mcp),
> then build browser **Three.js** apps/games around them with
> [`mint-threejs-skills`](https://github.com/mintdotgg/mint-threejs-skills).
> No local GPU, no model downloads — credits-based, free trial available.
---
## What's in this repo
| Path | Contents |
|------|----------|
| `skills/mint-mcp-3d-engine/` | Hermes skill: wiring Mint MCP + OAuth bearer flow, headless-host recipe, working scripts |
| `skills/mint-threejs-skills/` | Mint's official Three.js skill suite (app/game directors, visual/interaction systems, QA, debug) |
| `scripts/mint_generate.py` | Generate a model via Mint MCP and download the GLB |
| `scripts/mint_refresh_token.py` | OAuth token auto-refresh (run on a cron before expiry) |
| `assets/install-demo.gif` | Animated install walkthrough |
| `LICENSE` | MIT |
---
## Step 1 — Prerequisites
- **Node.js** ≥ 18 (for `npx skills`)
- **Hermes Agent** with MCP support (or any agent that reads `~/.hermes/skills`)
- A **Mint** account — free, sign up at [mint.gg](https://mint.gg) (Google/email)
- Git
```bash
node --version # v18+ required
hermes --version # any recent build with mcp_servers support
```
---
## Step 2 — Clone this repo
```bash
git clone https://github.com/Celebez/mint-threejs-setup.git
cd mint-threejs-setup
```
The skill folders under `skills/` are ready to symlink/copy into your agent.
---
## Step 3 — Install the Three.js skills
```bash
npx skills add mintdotgg/mint-threejs-skills -g -y
```
This clones the official suite and **symlinks it into Hermes Agent**
automatically (`~/.hermes/skills/mint-threejs-skills`). The suite includes:
- `threejs-app-director` — product configurators, viewers, interactive experiences
- `threejs-game-director` — games with a complete playable loop
- `threejs-visual-systems` — lighting, reflections, materials
- `threejs-interaction-systems` — orbit camera, selectors, controls
- `threejs-gameplay-systems` / `threejs-game-ui-designer` — game logic + UI
- `threejs-debug-profiler` / `threejs-qa-release` — debug & verify
> Also copy the bundled `mint-mcp-3d-engine` skill into your agent's skills dir:
> ```bash
> cp -r skills/mint-mcp-3d-engine ~/.hermes/skills/
> ```
---
## Step 4 — Wire Mint MCP into Hermes
Add the server to `~/.hermes/config.yaml` under `mcp_servers:`:
```yaml
mcp_servers:
mint-mcp:
url: https://mcp.mint.gg/mcp
auth: oauth
enabled: true
```
Then authenticate. **On a desktop (interactive) host:**
```bash
hermes mcp login mint-mcp
```
A browser opens → log in to Mint → approve the scopes
(`mint:read`, `mint:generate:start`, `mint:generate:approve`). Done.
### Headless host (no browser on the box)
`hermes mcp login` fails on a non-interactive host. Run the OAuth exchange
yourself: DCR + PKCE + token exchange, then drop the token at
`$HERMES_HOME/mcp-tokens/mint-mcp.json` (mode `0600`). Full step-by-step,
including a reusable loopback listener, is in
[`skills/mint-mcp-3d-engine/references/headless-oauth-recipe.md`](skills/mint-mcp-3d-engine/references/headless-oauth-recipe.md).
> ⚠️ **Key gotcha:** the approving browser MUST run on the **same host** as the
> listener, not a different machine. The `redirect_uri` is a loopback address; a
> browser on another machine redirects to its own localhost and the code is
> single-use — it gets burned.
Verify:
```bash
hermes mcp test mint-mcp
# ✓ Connected ✓ Tools discovered: 37
```
---
## Step 5 — Keep the token fresh (cron, no LLM)
Mint tokens expire in **1 hour**. The bundled
`scripts/mint_refresh_token.py` refreshes via `refresh_token` and rewrites the
token file (only when < 10 min remain). Schedule it every 50 minutes:
```bash
# Hermes cron (no_agent = no LLM cost)
hermes cron create --name mint-refresh --schedule "*/50 * * * *" \
--no-agent --script mint_refresh_token.py
```
Or a plain systemd timer / crontab line: `*/50 * * * * python3 /path/mint_refresh_token.py`.
---
## Step 6 — Generate your first 3D asset
```bash
python3 scripts/mint_generate.py "a modern minimalist trading workstation desk, dual monitors with forex charts, emerald dashboard, dark premium"
```
This starts the generation, polls until `succeeded`/`final`, then downloads the
GLB (+ preview webp) into `~/mint_3d/`. One generation ≈ **11 credits** on the
Explorer trial (20,000 free credits/month).
Or just ask your agent:
> "Use Mint MCP to create a trading workstation from a text prompt. Run
> generation automatically, wait for the finished artifact, return the
> downloadable GLB."
---
## Step 7 — Build a Three.js app
Load `mint-threejs-skills` and describe what you want. For a viewer/configurator
around the GLB you just pulled:
> "Build a responsive Three.js product viewer for `trading-workstation.glb`.
> Orbit controls, a bright inspection bay, material selection, camera presets.
> Use Mint MCP only as the asset pipeline — never call MCP in browser code."
The skill presents an **implementation plan for approval before building**
(same flow used by Mint's own
[Helios Form](https://play.mint.gg/helios-form) demo).
---
## Cost model
- Connecting the MCP endpoint is **free** (just OAuth login).
- Every generation consumes **Credits** (paid plan, or trial/bonus/referral at
signup). No unlimited free tier.
- No local GPU models to install — perfect for headless prototyping.
---
## License
[MIT](LICENSE) © 2026 Celebez
