@manycore/aholo-sdk-mcp

@manycore/aholo-sdk-mcp

Aholo OpenAPI 的本地 MCP Server，供 Cursor、Claude Desktop 等 Agent Studio 通过 stdio 调用 Aholo 能力。

底层封装公网 npm SDK（@manycore/aholo-sdk-*），支持：

• 文件上传（Asset）
• 3DGS 世界重建 / 生成（World）
• 多模态生图、四视图、图生/文生 3D、材质迁移、多格式导出与任务历史（Lux3D）

前置要求

• Node.js ≥ 18
• Aholo API Key
  • 中国区：https://labs.aholo3d.cn/api-keys
  • 海外：https://labs.aholo.ai/api-keys

快速开始

1. 配置 MCP

Cursor — 编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "aholo-sdk-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@manycore/aholo-sdk-mcp"],
      "env": {
        "AHOLO_API_KEY": "your_api_key_here",
        "AHOLO_REGION": "cn"
      }
    }
  }
}

Claude Desktop — 编辑配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "aholo-sdk-mcp": {
      "command": "npx",
      "args": ["-y", "@manycore/aholo-sdk-mcp"],
      "env": {
        "AHOLO_API_KEY": "your_api_key_here",
        "AHOLO_REGION": "cn"
      }
    }
  }
}

保存后重启 Agent / Studio，即可在对话中使用 Aholo 相关 tool。

2. 验证安装

AHOLO_API_KEY=your_key npx -y @manycore/aholo-sdk-mcp

未设置 AHOLO_API_KEY 时会提示并退出，属正常行为。

环境变量

变量	必填	说明
AHOLO_API_KEY	是	Aholo API Key。中国区在 labs.aholo3d.cn/api-keys 申请；海外在 labs.aholo.ai/api-keys 申请
AHOLO_REGION	否	cn（中国区，默认）或 com（海外）；也可在 tool 参数里传

使用说明

文件上传

本地文件通过 localPath 传入，由 SDK 直接读磁盘上传至 CDN，二进制不经过 MCP 协议。

World 重建（scene）

场景	选用 Tool
单个物体 / 产品 / 手办	world_reconstruct_object_from_files 或 world_reconstruct_object
室内 / 房间环拍	world_reconstruct_space_from_files 或 world_reconstruct_space

• 图片重建须 ≥ 20 张（.jpg/.jpeg/.png/.webp）；普通视频 resourceType=video（.mp4/.mov）；Insta360 全景 resourceType=insv（.insv）
• useMask=true 表示抠图（主体分割）
• taskQuality 默认 normal；用户说「快速预览」→ low，「高质量/专业」→ high

World 生成（Spatial Gen）

world_generate 用于 AI 生成世界（非多图重建）：

• 纯文案：只传 prompt
• 单张参考图：只传 localPath（内部先 upload_asset）
• 图文组合：prompt + localPath（至多 1 张图）

参考图只接受本地 localPath，不接受外部网络 URL。多图/视频请用 world_reconstruct_*。

长任务

提交类 tool 默认 wait=false，立即返回 worldId / taskId：

• 查进度：world_get / lux3d_get_task（推荐，非阻塞）
• 等到完成：world_wait_for / lux3d_wait_for_task（阻塞，可能占用连接数分钟）

Tools

推荐（scene 已固定）：

Tool	说明
world_inspect_local_media	只读：分析本地图片/视频，可选抽帧预览
world_reconstruct_object_from_files	本地文件 → 物体（model）重建
world_reconstruct_space_from_files	本地文件 → 室内（space）重建
world_reconstruct_object	URL → 物体（model）重建
world_reconstruct_space	URL → 室内（space）重建

兼容（须自行指定 scene 并确认）：

Tool	说明
world_reconstruct	URL 重建
world_reconstruct_from_files	本地文件重建

通用：

Tool	说明
upload_asset	上传本地文件，返回 CDN URL
world_generate	3DGS 世界生成（Spatial Gen）：纯文案 / 本地单图 / 图文（至多 1 张，走 localPath 上传）
world_get	查询 world 详情（只读）
world_wait_for	轮询 world 直至终态
world_list	分页列出 world（只读）

Lux3D

图生/文生 3D 的 version 必填，支持 G1 与 G1-Turbo。faceCount 范围为 10000–300000；outputFormat 支持 zip / glb / ply；aiPredictSize 控制是否预测尺寸。G1-Turbo 的 ZIP/GLB 输出还支持 enablePbr。图生 3D 的单图/多视角输入必须二选一。

Tool	说明
lux3d_multimodal_to_image	多模态生图：prompt 和/或 图片（img URL / localPath）至少一个
lux3d_image_to_four_view	图片 URL / 本地图 / 文案 → 四张标准视图（至少一项）
lux3d_img_to_3d_from_file	本地图片 → Lux3D 3D（localPath 单图 / localPaths 多视角）
lux3d_img_to_3d	图片 URL → Lux3D 3D（img / imgs）
lux3d_text_to_3d	文字 → Lux3D 3D
lux3d_material_transfer	参考图材质迁移到 GLB 模型（version 固定 v3.0-standard）
lux3d_multi_format_export	Lux3D ZIP/GLB → USDZ/OBJ/FBX/STL/3MF 导出
lux3d_part_split	GLB 部件拆分
lux3d_articulation_animation	GLB + 提示词，关节化与动画
lux3d_humanoid_auto_rig	数字人 GLB 自动绑骨
lux3d_humanoid_animation_retarget	已绑骨模型的动画重定向（1–10 个预设动作，GLB/FBX）
lux3d_list_tasks	分页查询 Lux3D 历史任务（只读；筛选 status 不含 6）
lux3d_get_task	查询 Lux3D 任务（只读）
lux3d_wait_for_task	轮询 Lux3D 任务

依赖 @manycore/aholo-sdk-core@^1.3.0、@manycore/aholo-sdk-asset@^1.3.0、@manycore/aholo-sdk-world@^1.4.0、@manycore/aholo-sdk-lux3d@^1.9.0。海外区域（region=com）默认请求 https://api.aholo.ai。任务结果仍可能包含 6（已取消）。

相关文档

• Aholo API 文档
• TypeScript SDK 指南
• World 重建 Skill（参考工作流）

从源码运行（可选）

git clone https://github.com/manycoretech/aholo-spatial-sdk.git
cd aholo-spatial-sdk/typescript/mcp   # 以仓库实际目录为准
npm install
npm run build
AHOLO_API_KEY=your_key npm start

本地调试时，将 Cursor 配置中的 command / args 改为指向构建产物：

"aholo-sdk-mcp": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/dist/index.js"],
  "env": {
    "AHOLO_API_KEY": "your_api_key_here",
    "AHOLO_REGION": "cn"
  }
}