跳到主要内容

MCP

Model Context Protocol（MCP） 让 Cursor、Claude Desktop 等 Agent Studio 通过标准协议调用 Aholo 能力。官方包 @manycore/aholo-sdk-mcp 在本地以 stdio 方式运行，底层封装 @manycore/aholo-sdk-* npm SDK。

使用前请先在 快速开始 申请 API Key，并阅读 授权。

MCP、Skill 与 SDK 怎么选​

方式适合谁典型场景
MCP（本页）在 Cursor / Claude 里用对话驱动上传本地文件、提交重建、查任务进度
Skill同上，偏工作流与参数约束复杂 3DGS 流程、SkillHub 一键安装
SDK写业务代码的开发者后端服务、脚本、生产环境集成

MCP 与 Skill 可配合使用：MCP 提供 tool 调用能力，Skill 提供对话策略与业务约束。

前置要求​

安装​

Cursor​

编辑 ~/.cursor/mcp.json（项目级可用 .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。在 Cursor 中可在 Settings → MCP 查看连接状态。

验证​

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

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

环境变量​

变量必填说明
AHOLO_API_KEY是Aholo API Key
AHOLO_REGION否cn（中国区，默认）或 com（海外）；也可在 tool 参数中指定
安全提示

请勿将 API Key 提交到公开仓库或分享给他人。推荐仅通过 mcp.json 的 env 或本机环境变量注入。

使用说明​

文件上传​

本地文件通过 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

长任务​

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

  1. 查进度（推荐）：world_get / lux3d_get_task
  2. 等到完成：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_objectURL → 物体（model）重建
world_reconstruct_spaceURL → 室内（space）重建

通用：

Tool说明
upload_asset上传本地文件，返回 CDN URL
world_generate文字生成 3D 世界
world_get / world_wait_for / world_list查询与轮询 world

Lux3D​

默认 v3.0-standard（省略 version 即用）。v3.0 成功时 outputs[0..4] 依次为 zip / glb / usdz / obj zip / fbx zip；未通过 needUsdz / needObj / needFbx 请求的槽位返回 NOT_REQUESTED。faceCount 对 v2.0-preview / v3.0-standard 生效（10000–500000，默认 60000）；v1.0-pro 忽略。

Tool说明
lux3d_img_to_3d_from_file / lux3d_img_to_3d / lux3d_text_to_3dLux3D 图生 / 文生 3D（支持 version / faceCount / need*）
lux3d_get_task / lux3d_wait_for_task查询与轮询 Lux3D 任务

当前 npm 包版本：@manycore/aholo-sdk-mcp@1.2.1（依赖 @manycore/aholo-sdk-lux3d@^1.3.0）。

完整说明见 npm 包 README。

相关文档​