MeshMend

MeshMend — MCP 服务

English · 中文

通过能在你的计算机上运行工具的 AI 助手，检查并修复 3D 打印网格（STL 和 3MF）。支持 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Codex CLI、Gemini CLI，以及任何能启动本地服务的其他 MCP 客户端。

你可以问 “~/prints/bracket.stl 是水密的吗？”、“为什么我的切片软件提示这个模型有孔洞？” 或 “把这个 3MF 转成 STL”：助手会读取你计算机上的文件，准确告诉你问题所在（孔洞、面片翻转、壳体朝向内侧、非流形边、重复三角形），如实说明自动修复能否解决问题，并在原文件旁写入修复后的副本。

你的文件绝不会离开你的计算机。 服务在本地运行，只读取和写入你指定的文件，不会发出网络请求，也没有遥测功能。原始文件绝不会被覆盖。它使用的网格代码与免费的浏览器内工具 mesh-mend.pages.dev 相同。

npx -y github:Keith-CY/meshmend-mcp

状态： 版本 0.1.0。发布到 npm 尚未完成；在此之前，npx -y github:Keith-CY/meshmend-mcp（需要 Node.js 18+ 和 git）会运行相同的构建版本；Claude Desktop 用户可以从 Releases 安装一键安装包。

工具

工具	输入	功能
check_mesh	path、unit?（mm/cm/in，仅限 STL）、item?（3MF 构建项目）	报告尺寸（单位为 mm）、三角形数量、壳体数量，以及每种问题的数量；还会报告内存中试运行修复的结果：ok、repairable、partly_repairable 或 needs_manual_review。只读。
repair_mesh	path、fill_holes?（默认 false）、max_hole_span_mm?（默认 20）、output_path?、unit?、item?、overwrite?	移除重复面和零面积面，使面片绕序保持一致，将朝向内侧的壳体翻转朝外，并可按需封闭平面孔洞。写入以 mm 为单位的二进制 STL，并报告修复前后的情况。
convert_3mf_to_stl	path、item?、output_path?、overwrite?	将 3MF 转换为以 mm 为单位的二进制 STL，并应用构建变换和单位，几何形状保持不变。

每个结果都会以易读文本和结构化 JSON 的形式返回（structuredContent，带有 outputSchema）。check_mesh 标记为只读；另外两个工具只会创建新文件（destructiveHint: false）。

结果保存位置： 与输入文件位于同一目录，文件名为 <name>.repaired.stl（转换时为 <name>.stl），若名称已存在，则依次添加 -2、-3……，不会替换任何文件。使用 output_path 时，只有在设置 overwrite: true 后才会替换现有文件，并且绝不会将输入文件作为输出文件。

连接

Claude Desktop

一键安装： 从 Releases 下载 meshmend-mcp-0.1.0.mcpb 并打开（或选择 Settings → Extensions → Advanced settings → Install extension…）。Claude Desktop 会使用内置的 Node.js 运行它。

或手动安装： 选择 Settings → Developer → Edit config，并添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "meshmend": {
      "command": "npx",
      "args": ["-y", "github:Keith-CY/meshmend-mcp"]
    }
  }
}

Claude Code

claude mcp add meshmend -- npx -y github:Keith-CY/meshmend-mcp

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "meshmend": { "command": "npx", "args": ["-y", "github:Keith-CY/meshmend-mcp"] }
  }
}

VS Code（GitHub Copilot）

.vscode/mcp.json：

{
  "servers": {
    "meshmend": { "type": "stdio", "command": "npx", "args": ["-y", "github:Keith-CY/meshmend-mcp"] }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：与 Cursor 相同的 mcpServers 配置块。

Codex CLI

~/.codex/config.toml：

[mcp_servers.meshmend]
command = "npx"
args = ["-y", "github:Keith-CY/meshmend-mcp"]

Gemini CLI

~/.gemini/settings.json：

{ "mcpServers": { "meshmend": { "command": "npx", "args": ["-y", "github:Keith-CY/meshmend-mcp"] } } }

其他客户端

任何能启动本地（stdio）服务的 MCP 客户端，都可以运行 npx -y github:Keith-CY/meshmend-mcp，或在克隆的代码库中运行 node /path/to/meshmend-mcp/dist/meshmend-mcp.js（该文件没有依赖项）。可直接使用的配置文件位于 examples/clients/。

请向助手提供绝对路径（~ 会展开）。相对路径会以服务的工作目录为基准解析；在桌面应用中，这个目录通常不是你的项目文件夹。

实际文件：修复前后

根据此仓库的测试和本地运行结果（npm test 会重复测试所有文件，但不包括兔子和球体）：

文件	check_mesh 发现的问题	结论	repair_mesh 修复后
MeshMend 的示例方块，30 × 24 × 24 mm，19 个三角形（missing-patch.stl）	1 个孔洞（4 条开放边），3 处绕序冲突，1 个重复面	可修复（使用 fill_holes）	已封闭：已移除重复面，修正朝向，并用 2 个三角形封住 10 × 8 mm 的孔洞；共 20 个三角形
trimesh 的 multibody.stl，32 个三角形	2 个内翻壳体，12 处绕序冲突	可修复	已封闭，且朝外
犹他茶壶（teapot.stl），894 个三角形	6 个开放边界（64 条开放边），1 个非流形顶点	需要人工审核	未更改，并说明了原因：孔洞是曲面的，非流形顶点需要人工判断
一份 CAD 导出文件（featuretype.STL），3,476 个三角形	16 条开放接缝（576 条开放边）	需要人工审核	未更改：顶点坐标不完全相同的表面无法连接，而 MeshMend 从不焊接相邻顶点
斯坦福兔子（bun_zipper.ply 转为 STL，缩放至 156 mm；未包含）	底部有 5 个开放边界（223 条开放边），共 69,451 个三角形	需要人工审核	即使跨度设为 200 mm 也未更改：扫描模型中的孔洞不是平面
生成的 100 mm 球体，247,499 个三角形，3 个孔洞，249 个翻转面	3 个开放边界（13 条开放边），744 处绕序冲突	部分可修复	已修正朝向，并封住 1 个平面孔洞；另外 2 个曲面孔洞留待审核。耗时约 10 秒

可以修复的问题和不能修复的问题

可以修复：

• 重复面和零面积（退化）面；
• 普通共边处面绕序不一致（法线翻转）的问题；
• 不与其他壳体重叠的内翻封闭壳体；
• 设置 fill_holes: true 时：边界顶点数为 3–128、且包围盒对角线不超过 max_hole_span_mm 的简单平面孔洞。

无法：

• 焊接相邻顶点（只会合并坐标完全相同的顶点），因此无法闭合表面之间的接缝；
• 拆分非流形边或顶点、重新网格化或重建实体；
• 修复自相交、合并重叠部分，或检查壁厚、悬垂或支撑；
• 封住曲面孔洞、嵌套开口或宽度超过跨度限制的孔洞；
• 保证模型可以打印。请在切片软件中打开结果。

由于有些开口是有意保留的，除非用户要求，否则不会填充孔洞。check_mesh 会先在内存中运行修复，因此在写入任何文件之前，其结论就能说明 repair_mesh 是否真的有帮助。

**限制：**每个文件不超过 30 MiB，且最多 250,000 个三角形（与网站限制相同）。对于 3MF：支持主构建、组件、变换、生产扩展中的部件引用和单位；遇到 ZIP64、不受支持的必需扩展、部件间单位混用和仅包含 G-code 的软件包时，会拒绝处理并说明原因。颜色、材质和打印设置不会保留到 STL 中。

隐私

MeshMend 的 MCP 服务只在你的计算机上运行。它会读取你或你的助手指定的文件，并写入新的 STL 文件；不会向任何地方发送数据，没有分析或遥测功能，也不会保留日志。与你的助手一样，你的 AI 助手会看到工具结果（计数、大小、文件路径和消息），并受该助手自身隐私条款的约束。

开发

npm install
npm test            # builds dist/ and runs the core, file and end-to-end tests (needs Bun)
npm run pack:mcpb   # builds the Claude Desktop bundle into build/
node scripts/call.mjs check_mesh '{"path":"tests/fixtures/missing-patch.stl"}'

src/core/ 是 MeshMend 的网格代码，直接从网站复制，未作任何更改，因此两者会给出相同结果。dist/meshmend-mcp.js 是一个打包后的单文件（已提交，因此 npx github: 无需构建步骤）；NOTICE 列出了打包所含的软件包及其许可证。

许可证

MIT。三个 trimesh 测试文件由其作者以 MIT 许可证授权（详情）。

浏览器版本提供 3D 预览和修复前后对比：mesh-mend.pages.dev。