meshcheck-mcp

meshcheck-mcp

Add deterministic 3D asset validation to your agent. meshcheck-mcp is a local-first Model Context Protocol server that lets any MCP client — Claude Code, Claude Desktop, Cursor, and others — validate, render, and inspect GLB/glTF 2.0 models through the meshcheck API.

It reads models straight off your disk by path, so an agent that just generated a model hands over a filename, not bytes. All the analysis runs server-side; this package is a thin, faithful client: file handling plus verbatim passthrough of meshcheck's machine-readable reports.

• Deterministic core. validate_model and render_model are pure measurement — the same input and profile give the same report. No 0–100 score, just per-check verdicts with a pass/warn/fail rollup.
• One non-deterministic surface, clearly labelled. inspect_model asks a vision model a semantic question ("does this look like a barrel?"). It is priced and isolated separately and says deterministic: false up front.
• Zero telemetry. The package phones home to nothing but the meshcheck API you configure.

Install & register

The server needs a meshcheck API key (mc_live_...) in its environment. Get one at meshcheck.dev.

Claude Code / Claude Desktop / Cursor (published package)

Once published to npm, register it with npx — no separate install step:

{
  "mcpServers": {
    "meshcheck": {
      "command": "npx",
      "args": ["-y", "meshcheck-mcp"],
      "env": { "MESHCHECK_API_KEY": "mc_live_..." }
    }
  }
}

In Claude Code you can do the same from the CLI:

claude mcp add meshcheck -s project -e MESHCHECK_API_KEY=mc_live_... -- npx -y meshcheck-mcp

From a packed tarball (pre-publish)

While the package is not yet on npm, install the tarball globally and register the plain command:

npm pack                              # in this directory → meshcheck-mcp-0.1.1.tgz
npm install -g ./meshcheck-mcp-0.1.1.tgz

{
  "mcpServers": {
    "meshcheck": {
      "command": "meshcheck-mcp",
      "args": [],
      "env": { "MESHCHECK_API_KEY": "mc_live_..." }
    }
  }
}

Configuration

Env var	Required	Default	Purpose
MESHCHECK_API_KEY	yes	—	Your meshcheck API key (mc_live_...). The server exits with a clear message if it is missing.
MESHCHECK_API_URL	no	https://api.meshcheck.dev/v1	API base URL. Override for staging or self-hosted deployments.

Tools

Tool	Deterministic	What it does
validate_model	yes	Runs meshcheck's checks (geometry, UV, texture, performance budgets) and returns the full report JSON with a pass/warn/fail rollup.
render_model	yes	Renders screenshots with a fixed studio camera rig; returns the render JSON plus the first few stills inline so the agent can look at the asset.
inspect_model	no	Asks a vision model a semantic question about the model. An opinion surface, priced and isolated separately.
get_report	yes	Re-fetches a stored report by id (free, no credits).

Every tool takes either a local path or a public url (exactly one). Large files (≥ ~4.4 MB) are uploaded through meshcheck's presigned Blob flow automatically; asynchronous jobs (turntables, very large models) are polled internally so you always get the finished report, never a job envelope.

validate_model

validate_model({
  path?: string,            // local file path (read + uploaded for you)
  url?: string,             // or a public URL
  profile?: "web" | "mobile" | "pc" | "hero",
  overrides?: { [param: string]: number },   // e.g. { max_tris: 15000 }
  checks_only?: boolean     // skip rendering for faster results
})

Returns the full report JSON (see the report schema): verdict, per-check measured/threshold/ status, stats, and (unless checks_only) screenshots.

render_model

render_model({
  path?: string, url?: string,
  angles?: { rv: number, rh: number }[],     // custom camera angles; omit for the standard set
  size?: number,                              // still size in pixels (default 1024)
  turntable?: { frames?: number, size?: number, format?: "gif" }  // animated GIF (always async)
})

Returns the render response JSON (signed screenshot URLs + stats) and, inline, the first up to three still images so the agent can look at the model immediately.

inspect_model

inspect_model({
  path?: string, url?: string,
  check: "VIS-001" | "VIS-002" | "VIS-003",
  prompt?: string,      // VIS-001: text prompt to match against
  question?: string     // VIS-003: free-form question
})

Non-deterministic — a vision model's opinion, not a measurement. Use validate_model for anything measurable.

get_report

get_report({ report_id: string })   // report_id or render_id from an earlier call

Errors

Errors are passed through from the API verbatim as structured JSON, with the tool result flagged isError. The MCP layer adds no interpretation:

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "...", "detail": { "balance": 0, "needed": 2 } } }

Client-side failures (a missing file, a file larger than your plan allows) use the same envelope shape with codes like FILE_NOT_FOUND and FILE_TOO_LARGE.

Example: generate → validate → fix loop

1. Your agent generates model.glb on disk.
2. validate_model({ path: "model.glb", profile: "web" })
   → verdict "fail", PERF-001 fail: 48,231 triangles exceeds budget of 15,000.
3. Your agent regenerates with a lower triangle target.
4. validate_model({ path: "model.glb", profile: "web" })
   → verdict "pass".

Privacy

Uploaded model bytes are deleted immediately after processing. Reports are retained 30 days; screenshots are served via signed URLs that expire with the report. See meshcheck.dev for the full commitments.