3d-eyes 👁️

Give your coding agent eyes for 3D.

An MCP server that lets Claude Code (or any MCP client) see and diagnose 3D files - meshes and Gaussian splats - with zero GPU / OpenGL / Blender dependency. Pure numpy rendering: it runs on any machine, any container, any CI.

中文文档 · Agent Skill · Broken zoo

---

Your agent can write Three.js all day, but until now it debugged 3D files blind. Ask it "why is my model black?" and it guesses. With 3d-eyes it looks:

That's inspect_scene on a real broken file: six orthographic views plus perspective, inward-facing triangles painted red, and a JSON report that says exactly what's wrong:

{
  "severity": "error",
  "summary": "All face normals are inverted (negative enclosed volume).",
  "symptom": "Model renders dark/black or shows red faces on every side.",
  "fix": "Invert face winding: mesh.invert() in trimesh, or flip normals on export."
}

The agent fixes the file, then proves it with diff_renders:

Gaussian splats too

3d-eyes speaks 3DGS: .ply (training output layout) and .splat. It renders turntable previews and runs a quality report with density-adaptive floater detection - the isolated blobs your training run left hanging in space:

"floaters": { "floater_count": 60, "floater_fraction": 0.0099,
              "examples": [[3.4, -2.8, 3.1], ...] }

Quickstart

# Claude Code
claude mcp add 3d-eyes -- uvx 3d-eyes

# or from source
git clone https://github.com/murphy977/3d-eyes && cd 3d-eyes
pip install -e . && claude mcp add 3d-eyes -- 3d-eyes

Then ask your agent things like:

"Check assets/robot.glb before I ship it." "My model renders black in Three.js - here's the file." "Are there floaters in scene.splat?"

For best results, install the Agent Skill so your agent knows the symptom → cause table by heart:

mkdir -p ~/.claude/skills/3d-debugging && cp skill/SKILL.md ~/.claude/skills/3d-debugging/

Tools

Tool	What it does
inspect_scene(path)	Contact sheet (6 ortho + perspective views) + structure stats + defect report. Red = faces seen from behind. Auto-detects splat files.
render_views(path, cameras)	Custom angles: [{"azimuth": 30, "elevation": -60, "distance": 1.2, "ortho": false}] - zoom in, look underneath, get exact silhouettes.
diff_renders(path_a, path_b)	Same-camera side-by-side of two files, plus both defect verdicts. Verify every fix.

Detects: flipped/inconsistent normals · degenerate faces · non-manifold edges · missing texture/buffer references · scale unit mistakes (mm vs m) · splat floaters · nearly-transparent splat bloat. Corrupt files return a parse diagnosis instead of a crash.

Formats: GLB, GLTF, OBJ, PLY, STL (meshes) · 3DGS PLY, .splat (Gaussian splats).

Try it on the broken zoo

Every defect has a minimal sample file in examples/broken-zoo/:

3d-eyes inspect examples/broken-zoo/cube_flipped_normals.obj   # all red + report
3d-eyes inspect examples/broken-zoo/torus_with_floaters.ply    # 60 floaters found
3d-eyes diff examples/broken-zoo/cube_flipped_normals.obj fixed.obj

(The CLI mirrors the MCP tools - handy for humans and CI pipelines.)

Why software rendering?

Agents run everywhere: laptops, devcontainers, CI runners, remote boxes. Any renderer that needs EGL/OSMesa/GPU drivers will eventually fail on one of them. 3d-eyes rasterizes with numpy + PIL - preview quality by design, 100% portability by design. An agent doesn't need path tracing to see that your normals are flipped.

Roadmap

• [ ] .spz splat format
• [ ] Texture-mapped rendering
• [ ] USD support
• [ ] Animation / skeleton sanity checks
• [ ] Optional pyrender backend for high-quality output
• [ ] Screenshot-vs-render comparison for engine-side bug isolation

Issues and PRs welcome - the codebase is small and readable on purpose.

License

MIT