PicoBerry

PicoBerry MCP 服务

通过任意 MCP 客户端（Claude Code、Cursor、Claude Desktop、Cline）为游戏和 3D 工作流生成 3D 模型、图像和动画，无需编写 HTTP 胶水代码。它是 PicoBerry /v1 API 的轻量封装，让你可以直接在 Agent 中使用 PicoBerry 的多引擎工作流。多个 3D 和图像引擎共用一个 API；调用 list_models 可查看当前可用引擎及各引擎的费用。生成的素材是草稿，适合用于原型制作和迭代，也可以针对你的项目进行审核或完善。

📖 完整参考文档： API + MCP 文档 · PicoBerry API

MCP 或 API 不需要单独订阅。 生成内容会像使用 Web 应用一样，按引擎消耗相同的 PicoBerry 预付额度。你可以在消耗额度前调用 list_models 查看费率。（使用 API 需要先完成购买，详见获取 API 密钥。）

安装

无需安装——使用 npx 运行：

// Claude Code:  .mcp.json   ·   Claude Desktop:  claude_desktop_config.json
{
  "mcpServers": {
    "picoberry": {
      "command": "npx",
      "args": ["-y", "@picoberry/mcp-server"],
      "env": {
        "PICOBERRY_API_KEY": "pb_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor 使用相同的配置格式，配置文件路径为 ~/.cursor/mcp.json。

获取 API 密钥

登录 https://picoberry.ai，打开控制面板中的 API Keys 选项卡，然后点击 Create key。密钥只会显示一次——请立即复制并像密码一样妥善保管。

使用 API 需要先完成购买：订阅或一次性额度包均可。购买后，你将永久获得 API 使用资格——无需保持当前有效订阅。（当然，正在生效的付费订阅也可以。）

环境变量

变量	必需	默认值	说明
PICOBERRY_API_KEY	✅	—	pb_live_...
PICOBERRY_API_BASE	—	https://api.picoberry.ai	如果没有收到其他主机地址，请留空

工具

工具	功能
list_models	查看某个类别（3d / image / parts-board / remesh / texture / animate）的引擎及额度费用。生成前请先调用——不要将引擎名称写死在代码中。
list_animation_presets	列出动画预设 ID（因引擎而异），支持可选的子字符串筛选。
get_credits	查看当前额度余额。
generate_image	文本 → 图像（可选参考图像 URL）。count（1–4）可在一次调用中生成多张图像 → assets[]，请分别等待每个 ID。
generate_3d_from_text	文本 → 3D 模型（GLB）。
generate_3d_from_image	图像 → 3D 模型。单视图：image_url 或本地 image_path。多视图（2–4 个视角，保真度更高）：image_urls 或 image_paths，按 [正面、左侧、背面、右侧] 排列——仅支持 tripo*/meshy6/hunyuan-3.x。
parts_board	将一张图像拆分为分解零件板图像（使用服务端固定引擎）。输入 asset_id、image_url 或本地 image_path；将结果传给 generate_3d_from_image，即可生成零件分离的网格。
remesh	对现有 3D 素材进行重拓扑处理 → 新素材。
texture	为现有 3D 素材重新制作纹理（PBR）→ 新素材。
animate	为现有 3D 角色自动绑定骨骼并制作动画 → 新素材。
get_asset	查看单个素材的状态和结果 URL。
wait_for_asset	轮询素材直至完成（或超时），然后返回该素材。
list_my_assets	浏览你生成的素材。
download_asset	导出已完成的 3D 素材（glb / fbx / obj）→ 签名 URL。

生成流程

生成是异步的：

1. generate_3d_from_text({ prompt }) → 返回素材 { id }。
2. wait_for_asset({ asset_id: id }) → 轮询直至 taskStatus === 2（成功）。
3. 从 files.model（GLB）或 files.image（PNG）中读取结果 URL。

taskStatus：0 等待中 · 1 处理中 · 2 成功 · 3 失败。结果 URL 带签名且有效期较短——请及时下载。发生错误时会返回可操作的提示信息（例如，未知引擎会返回有效名称列表）。

示例（在 Agent 中）

“制作一个低多边形宝箱，将其拓扑重构至 3k 个三角面，并提供一个 Unity FBX 文件。”

list_models(category="3d")                         → pick an engine
generate_3d_from_text(prompt="low-poly treasure chest")  → { id: A }
wait_for_asset(asset_id=A)                          → taskStatus 2
remesh(asset_id=A, polycount=3000)                  → { id: B }
wait_for_asset(asset_id=B)
download_asset(asset_id=B, format="fbx", texture_preset="unity")  → signed URL

配合 Blender MCP 使用

将其与 blender-mcp 一起运行， Agent 就可以使用 PicoBerry 生成模型，然后在一个流程中将其导入 Blender：

{
  "mcpServers": {
    "picoberry": { "command": "npx", "args": ["-y", "@picoberry/mcp-server"], "env": { "PICOBERRY_API_KEY": "pb_live_..." } },
    "blender":   { "command": "uvx", "args": ["blender-mcp"] }
  }
}

开发

npm install
npm run build      # tsc → dist/
PICOBERRY_API_KEY=pb_live_... npm start

发布

运行 Actions → Publish → Run workflow（或推送一个 v* 标签）。它会先发布到 npm，再发布到官方 MCP 注册表——注册表会通过获取软件包的 npm 元数据，并将其 mcpName 与 server.json 中的 name 进行匹配来验证，因此必须先发布到 npm。 保护步骤会在发布任何内容之前检查所有约束（名称／版本一致、命名空间大小写、 版本尚未发布到 npm），因为 npm 版本不可变，而且发布流程中途失败会浪费该版本号。

在 package.json 和 server.json（version 和 packages[0].version）中都更新 version——如果两者不一致，保护步骤会使运行失败。

一次性设置——无需密钥。 两次发布都通过工作流的 GitHub OIDC 令牌（id-token: write）进行身份验证。无需存储或轮换任何内容。

唯一需要做的是告知 npm 信任此工作流。在 npmjs.com 上，前往 @picoberry/mcp-server → Settings → Trusted publishing → GitHub Actions，并填写：

字段	值
组织或用户	UModeler
仓库	picoberry-mcp
工作流文件名	publish.yml
环境名称	（留空）
允许的操作	npm publish

工作流文件名必须完全匹配——这是 npm 验证内容的一部分。

MCP 注册表无需任何设置：mcp-publisher 会交换 Actions OIDC 令牌，注册表则根据令牌的 repository_owner 声明授予 io.github.<repository_owner>/*。这涵盖 io.github.UModeler/picoberry-mcp，并且无需交互式浏览器登录（该登录还需要组织 Owner 权限）。

Trusted Publishing 需要 npm >= 11.5.1，因此工作流使用 Node 24 （npm 11.x）。Node 22 仍捆绑 npm 10.9，运行会失败——node-version 固定值至关重要。如果运行器提供的 npm 版本过旧，保护步骤会提前使运行失败。

命名空间按字节精确匹配——必须是 io.github.UModeler/...，与 GitHub 组织的登录名一致。小写的 io.github.umodeler/... 会被拒绝并返回 403。

发布后，认领 Glama 列表 ——未认领的服务可发现性有限，而且 awesome-mcp-servers 要求其 PR 在 CI 中包含 Glama 徽章。

许可证

MIT