AI 集成
通过 Meshy CLI 或 Meshy MCP server 将 AI agent 和编码助手连接到 Meshy,以生成模型;也可以使用 llms.txt 和 llms-full.txt 来阅读文档。
如果你的 agent 可以运行 shell 命令,比如 Claude Code、Cursor 和 Codex,就使用 CLI 或 MCP server。如果它只能通过 MCP 连接工具,就安装 MCP server。如果你的聊天 agent 两者都不支持,就让它访问 https://docs.meshy.ai/llms.txt。
CLI 还是 MCP
两者调用的是同一个 Meshy REST API,价格也相同。它们的区别在于由谁来运行,以及如何登录。
| Meshy CLI | MCP server | |
|---|---|---|
| 运行者 | 你在终端中运行,脚本、CI,以及能运行 shell 命令的 agent | 通过 MCP 连接工具的 AI 应用 |
| 登录 | 在浏览器中登录一次。API key 是可选的,用于 CI。 | 在客户端的配置中填写 API key |
| 安装 | npm install -g meshy-cli | 每个客户端一条命令或一项配置(见下文) |
| 适用场景 | 脚本、批处理任务、CI、下载以及 3D 打印准备 | 在无法运行 shell 命令的聊天应用中以对话方式使用,例如 Claude Desktop |
要开始使用 CLI,请参阅 Meshy CLI。本页其余部分将介绍 MCP server。
什么是 MCP
Model Context Protocol (MCP) 是一个开放标准,让 AI 助手能够调用外部工具并获取结构化上下文。Meshy MCP server 将 Meshy REST API 封装为你的 agent 可以调用的工具。借助这些工具,agent 可以生成模型、检查任务状态并下载结果,而无需手写 HTTP 代码。
MCP server 是开源的。它以 @meshy-ai/meshy-mcp-server 的形式发布在 npm 上,其源代码位于 GitHub 上的 meshy-mcp-server 仓库 中。
你需要一个 Meshy API key。可以在 Developer Platform 的 API Keys 页面 创建。MCP server 会从 MESHY_API_KEY 环境变量中读取它。
安装 MCP server
要安装 server,请使用与你的 AI 客户端对应的标签页。将 msy_YOUR_API_KEY 替换为你的 API key。每种设置方式都会将 key 保存在用户级配置中,而不是项目内,因此不会出现在代码仓库里。
# macOS / Linux / WSL
claude mcp add -s user meshy --env MESHY_API_KEY=msy_YOUR_API_KEY -- npx -y @meshy-ai/meshy-mcp-server
# Windows (PowerShell or Command Prompt)
claude mcp add -s user meshy --env MESHY_API_KEY=msy_YOUR_API_KEY "--" cmd /c npx -y @meshy-ai/meshy-mcp-server
在 Windows 上,请通过 cmd /c 启动上述 JSON 配置中的 server:将 "command" 设置为 "cmd",将 "args" 设置为 ["/c", "npx", "-y", "@meshy-ai/meshy-mcp-server"]。不要在 PowerShell 中把 JSON 作为命令参数传递,因为 PowerShell 会去除其中的引号。
更喜欢技能包?开源的 meshy-3d-agent 技能包提供了现成的 Meshy 工作流,比如生成模型、跟踪任务状态以及下载结果。它可在 Claude Code、Cursor、Codex、OpenClaw 和 Hermes Agent 中使用。这些技能运行在 Meshy CLI 之上,而不是 MCP server。你只需在浏览器中登录一次,因此不需要 API key。它们要求 Node.js 22.12 或更高版本。要设置 CLI,请参阅 Meshy CLI。
npx skills add meshy-dev/meshy-3d-agent
可用工具
MCP server 将 Meshy REST API 以下列工具的形式提供,按功能分组。
3D 生成
meshy_text_to_3d:根据文本 prompt 创建未贴图的预览 meshmeshy_image_to_3d:根据一张图片创建 3D 模型meshy_multi_image_to_3d:根据同一物体的多张图片创建 3D 模型meshy_text_to_3d_refine:为预览 mesh 添加 texture
后处理
meshy_remesh:更改现有模型的 topology 或 polycount,或两者同时更改meshy_retexture:为现有模型应用新的 texturemeshy_rig:为 3D 人形角色添加骨骼meshy_animate:为已添加骨骼的角色应用 Animationmeshy_convert:将模型 Convert 为其他文件格式meshy_resize:将模型调整为真实世界尺寸meshy_uv_unwrap:为模型生成新的 UV 布局meshy_text_to_motion:根据文本 prompt 生成动画meshy_list_animations:免费查询预设动画动作的 ID
Creative Lab
meshy_creative_lab:将照片转换为完整的 Creative Lab 产品(运行 prototype 和 build 任务)
图像生成
meshy_text_to_image:根据文本创建 2D 图像meshy_image_to_image:根据参考图像创建 2D 图像
任务管理
meshy_get_task_status:检查任务状态和下载链接meshy_list_tasks:列出最近的任务,可选按类型或状态筛选meshy_cancel_task:删除任务。对于PENDING状态的任务,Meshy 会将其移除并退款;对于已完成的任务,则会将其删除。IN_PROGRESS状态的任务无法取消,API 会返回409。meshy_download_model:下载已完成的模型文件并保存到本地
Workspace
meshy_list_models:列出你最近的 Text to 3D 模型。对于其他任务类型,请使用meshy_list_tasks。
3D 打印
meshy_send_to_slicer:查找你电脑上安装的切片软件,并返回一条可在其中打开模型的命令。它在本地运行,不会调用 Meshy API。meshy_analyze_printability:免费检查模型的 FDM printability,包括水密性、体积、孔洞、非流形边和退化面meshy_process_multicolor:将带 texture 的模型 Convert 为用于打印的多色 3MF 文件meshy_repair_printability:修复模型以用于 FDM 打印meshy_auto_split:将模型拆分为可单独打印的部件
账户
meshy_check_balance:查看你剩余的积分meshy_list_usage:列出你团队已完成的 API 任务及每个任务消耗的积分,适用于 Studio 和 Enterprise 团队
工具名称和行为可能会发生变化。完整列表请参阅 MCP server 源代码 中的工具。
示例 prompt
首先,可以在支持 MCP 的聊天中尝试以下 prompt:
Generate a 3D fox from the prompt "a cartoon fox sitting", preview it, then
texture it with PBR maps. Download the final GLB to ./outputs.
Take the image at https://example.com/sculpture.jpg and convert it into a
riggable 3D character. Use `should_remesh: true` and 50k target polycount.
What's my current Meshy credit balance?
List my last 10 successful text-to-3d tasks and download the top 3 as GLB
into ./downloads/.
llms.txt 和 llms-full.txt
如果你的 agent 不支持 MCP,或者你想直接将 Meshy 文档放入 prompt 中,可以让它访问文档的纯文本版本:
llms.txt:一个精简索引,包含集成说明,比如如何轮询异步任务、authentication、速率限制、模型选择以及常见错误。llms-full.txt:将所有 API 页面合并在一个文件中,方便 agent 一次请求读取全部文档。- 按页 Markdown:在任意 endpoint URL 后添加
.md,例如https://docs.meshy.ai/api/text-to-3d.md。
文档站点每次构建时,Meshy 都会重新生成这三个文件,使其与 HTML 文档保持一致。
常见问题
- MCP server 是无状态的吗?
- 它不会存储你的凭据。server 会将你的 MESHY_API_KEY 保存在内存中,且从不写入磁盘。默认情况下,它会将下载的模型及其元数据保存在其工作目录下的 meshy_output 文件夹中。要将下载内容保存到其他位置,可以给下载工具提供一个 save_to 路径。
- MCP 的费用和 REST API 一样吗?
- 是的。MCP 工具调用执行的是相同的 REST 调用,并以相同的费率消耗积分。具体价格请参阅 Pricing 页面。
- 速率限制是多少?
- MCP server 的调用与你的 REST API 调用共享相同的速率限制。各个方案的具体限制请参阅速率限制页面。
- MCP server 可以访问哪些 Meshy 数据?
- 仅限你的 MESHY_API_KEY 能通过 REST API 访问的内容,权限也完全相同。
- 我该如何反馈问题?
- 请在 GitHub 上的 meshy-mcp-server 仓库中提交 issue:https://github.com/meshy-dev/meshy-mcp-server/issues