vrm-toolkit-mcp

vrm-toolkit-mcp

v0.1.1 — npm / GitHub

一个 MCP（模型上下文协议）服务，可让 AI Agent 检查、验证并预览本机上的 VRM / VRMA 文件。提供 5 个工具，使用 stdio 传输，运行时无需网络访问。

这是一个 MCP 服务，可让 AI Agent 检查 VRM / VRMA 文件、提取信息并预览。提供 5 个工具，使用 stdio 传输，运行时无需网络访问。

工具

工具	功能	说明
vrm_inspect	结构化 JSON：元数据（名称/作者/许可及权限字段）、人形骨骼映射、表情、多边形/纹理统计信息	结构化输出元数据（名称/作者/许可及权限）、骨骼、表情、多边形/纹理规模
vrm_validate	问题列表：缺少必需的人形骨骼、节点引用失效、缺少元数据/许可字段、未知的必需扩展，以及可配置的大小/三角形/纹理预算	检查列表：人形映射缺失、引用失效、元数据/许可缺失、未知的必需扩展、超出大小限制等
vrma_inspect	动画轨道、目标人形骨骼、表情轨道、时长、估算帧率	动画轨道、目标骨骼、表情轨道、时长、估算帧率
vrma_preview	将 VRMA 应用于 VRM，并通过本地无头 Chrome/Edge 渲染 PNG 静帧或短 WebM 视频（最长 10 秒）	将 VRMA 应用于 VRM，并使用本地无头 Chrome/Edge 导出 PNG 静帧或短 WebM 视频
vrm_snapshot	渲染静止姿势的 PNG，可选表情权重和视图预设（正面/四分之三侧面/侧面/面部特写）	可指定表情权重和视图预设（正面/斜侧面/侧面/面部特写）来生成静止姿势截图

结构类工具（vrm_inspect、vrm_validate、vrma_inspect）在 Node 中直接解析 GLB/glTF 容器，无需浏览器。渲染类工具（vrma_preview、vrm_snapshot）通过 puppeteer-core 使用已安装的 Chromium 系浏览器，不会下载任何内容。

支持的输入：VRM 0.x（extensions.VRM）、VRM 1.0（extensions.VRMC_vrm）、VRMA（extensions.VRMC_vrm_animation）、GLB 容器或纯 glTF JSON。

运行条件

• Node.js 20+
• 对于 vrma_preview / vrm_snapshot：本地 Chrome 或 Edge （自动检测；可通过 VRM_TOOLKIT_CHROME 环境变量指定）
• 输入大小限制：默认 512 MiB（可通过 VRM_TOOLKIT_MAX_BYTES 覆盖）

设置

注册到 Claude Code：

claude mcp add vrm-toolkit -- npx -y vrm-toolkit-mcp

其他 MCP 主机：命令为 npx，参数为 ["-y", "vrm-toolkit-mcp"]（stdio）。

从源代码安装：

npm install
npm run build
claude mcp add vrm-toolkit -- node /absolute/path/to/vrm-toolkit/dist/main.js

执行示例

以下为本地测试运行（2026-08-05）的实际输出（文件路径已缩短）。 以下为本地测试运行（2026-08-05）的实际输出（路径已缩短）。

vrm_inspect

输入：由 VRoid Studio 导出的 VRM 1.0 虚拟形象（15.7 MB）。

{
  "file": { "path": "...\\V1.vrm", "bytes": 15737992, "container": "glb" },
  "vrm": { "specFamily": "vrm1", "specVersion": "1.0" },
  "meta": {
    "name": "V1",
    "authors": ["D"],
    "licenseUrl": "https://vrm.dev/licenses/1.0/",
    "avatarPermission": "onlyAuthor",
    "commercialUsage": "corporation",
    "creditNotation": "required",
    "allowRedistribution": false,
    "modification": "prohibited"
  },
  "humanoid": {
    "mappedBoneCount": 54,
    "bones": [
      { "bone": "hips", "node": 1, "nodeName": "J_Bip_C_Hips" },
      { "bone": "spine", "node": 34, "nodeName": "J_Bip_C_Spine" }
    ],
    "missingRequiredBones": []
  },
  "expressions": { "presetCount": 14, "presets": ["happy", "angry", "sad", "..."] },
  "geometry": {
    "meshCount": 3,
    "totalVertices": 103489,
    "totalTriangles": 33484,
    "perMesh": [
      { "name": "Face (merged)", "vertices": 33640, "triangles": 7308 },
      { "name": "Body (merged)", "vertices": 57128, "triangles": 11548 },
      { "name": "Hair001 (merged)", "vertices": 12721, "triangles": 14628 }
    ]
  },
  "textures": { "imageCount": 26, "totalImageBytes": 8033934, "maxDimension": 2048 },
  "materials": { "materialCount": 17 }
}

（为便于阅读，输出已截断；工具会返回完整的骨骼和图像列表。）

vrma_inspect

{
  "file": { "path": "...\\motion-walk-forward.vrma", "bytes": 3268, "container": "glb" },
  "vrma": { "specVersion": "1.0" },
  "humanoid": { "mappedBoneCount": 16, "bones": ["hips", "spine", "chest", "head", "..."] },
  "animation": {
    "animationCount": 1,
    "channelCount": 2,
    "channelsByPath": { "translation": 1, "rotation": 1, "scale": 0, "weights": 0 },
    "totalKeyframes": 62,
    "durationSec": 1.25,
    "fpsEstimate": 24,
    "frameCountEstimate": 31,
    "humanoidBoneTracks": [
      { "bone": "hips", "paths": ["translation"] },
      { "bone": "chest", "paths": ["rotation"] }
    ]
  }
}

vrm_validate

带有稳定代码和严重级别的问题列表：

{
  "ok": false,
  "errorCount": 1,
  "warningCount": 1,
  "findings": [
    { "severity": "error", "code": "HUMANOID_REQUIRED_BONE_MISSING",
      "message": "required humanoid bone is not mapped: leftHand (vrm1 required set)" },
    { "severity": "warning", "code": "META_LICENSE_OTHER_URL_MISSING",
      "message": "licenseName is Other but otherLicenseUrl is empty" }
  ]
}

vrm_snapshot / vrma_preview

{
  "output_path": "...\\v1-three-quarter-snapshot.png",
  "format": "png", "bytes": 194005, "width": 768, "height": 1024,
  "view": "three_quarter", "pose": "rest", "humanoid_bone_count": 54
}

{
  "output_path": "...\\v1-walk-preview.webm",
  "format": "webm", "bytes": 313597, "width": 768, "height": 768,
  "clip_duration_sec": 1.25, "recorded_duration_sec": 3, "fps": 30
}

错误代码

每次失败都会返回以下结构化工具错误之一： FILE_NOT_FOUND、SIZE_BUDGET_EXCEEDED、NOT_A_GLB、NOT_A_VRM、NOT_A_VRMA、 BROWSER_NOT_FOUND、RENDER_FAILED、OUTPUT_WRITE_FAILED。 即使输入文件有问题，服务进程也不会崩溃。

隐私

所有处理均在本地进行。服务不会建立网络连接、发送遥测数据，只会写入你指定的输出文件。/ 所有处理都在本地进行。不会建立网络连接或发送遥测数据，且只会写入指定的输出文件。

开发

npm test   # build + 25 self-verification tests (structural, boundary, headless rendering)

如果未找到本地 Chrome/Edge，渲染测试会跳过并显示提示。

许可证

MIT（参见 LICENSE）。/ MIT 许可证（参见 LICENSE）。