@manycore/aholo-sdk-mcp
v1.7.0
Published
Local stdio MCP server for Aholo OpenAPI (upload, world, and Lux3D generation, material, export, and task APIs).
Readme
@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
快速开始
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.aholo3d.com/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_list_tasks | 分页查询 Lux3D 历史任务（只读；筛选 status 不含 6） |
| lux3d_get_task | 查询 Lux3D 任务（只读） |
| lux3d_wait_for_task | 轮询 Lux3D 任务 |
依赖 @manycore/aholo-sdk-lux3d@^1.7.0。任务结果仍可能包含 6（已取消），查询结果包含 bizId。
相关文档
从源码运行（可选）
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"
}
}