Tripo AI · MCP Server + 本地 3D 查看器

把官方 tripo3d Python SDK 包装成 MCP Server，让 AI 客户端（Qoder / Claude Desktop / 任何 MCP 客户端）能用自然语言生成 3D 模型；再附一个零外网依赖的本地 three.js 查看器看模型。

MCP 一句白话：让 AI 助手“长出手”的标准接口，接上就能调用真工具。本项目就是把 Tripo 的 3D 生成能力做成这样一只手。

对中国网络特别友好：国内 .com 直连 / 海外 .ai + 本地代理两种模式一键切换。

✨ 能做什么

• 💬 对话生成 3D：「生成一个 low-poly 小狐狸」→ 自动出 GLB 模型

• 🖼 图生 3D：给张图 → 转成 3D 模型

• 🔧 9 个工具：查余额、文生 3D、图生 3D、精修、转格式（GLTF/FBX/OBJ/STL/USDZ/3MF）等

• 🎮 本地查看器：旋转/缩放/线框/截图，含旋转鸡块热梗复刻页

• 🇨🇳 网络友好：绕开 .ai 域名被墙问题，支持走代理

Related MCP server: GoModelHub 3D MCP

📁 目录结构

tripo-mcp-cn/
├── server.py           # MCP Server（9 个工具 + 代理补丁）
├── requirements.txt    # 4 个依赖
├── .env.example        # 配置模板（复制成 .env 填 Key）
├── output/             # 生成的模型落这里（gitignore，不入库）
├── examples/           # 仓库自带示例：小狐狸 + 鸡块（clone 即可看）
└── viewer/             # 本地 three.js 3D 查看器
    ├── serve.py        #   零依赖 HTTP 服务
    ├── index.html      #   通用查看器
    ├── nugget.html     #   旋转鸡块复刻页
    └── vendor/         #   three.js 库（已本地化，不连外网）

🚀 快速开始（3 步）

前置要求：Python ≥ 3.10（官方 SDK 用了新语法，3.9 会直接报错），python --version 先确认。

1. 装依赖

pip install -r requirements.txt

2. 配 Key

复制 .env.example 为 .env，填入你的 API Key（下面二选一模式）。

获取 Key：登录 Tripo 平台 → 头像 → API Keys → 创建（tsk_ 开头，SDK 强校验前缀）。

⚠️ 国内网络直连 .ai 域名会被 DNS 污染、访问不了，所以模式 A 必须配本地代理（FlClash / Clash Verge 等）。这也是本项目给 server.py 打 aiohttp trust_env 补丁的原因——让官方 SDK 自动读取 HTTPS_PROXY。

.env 示例（模式 A）：

TRIPO_API_KEY=tsk_你的key
TRIPO_IS_CHINA=false
HTTPS_PROXY=http://127.0.0.1:7890   # 端口按你的梯子客户端填：FlClash 默认 7890 / Clash Verge 默认 7897
NO_PROXY=localhost,127.0.0.1,.tripo3d.com

3. 挂到 MCP 客户端

以 Qoder 为例（其它客户端 mcpServers 格式通用）：

{
  "mcpServers": {
    "tripo": {
      "command": "python",
      "args": ["绝对路径/tripo-mcp-cn/server.py"]
    }
  }
}

• UI 方式：Settings → 搜 MCP → Add Server → 粘贴上面配置

• 文件方式（找不到 UI 时）：直接写进 Qoder 的 mcp.json（Windows：%APPDATA%\Qoder\SharedClientCache\mcp.json；macOS：~/Library/Application Support/Qoder/SharedClientCache/mcp.json），然后 Ctrl+Shift+P → Reload Window

看到 tripo 带 绿点 ✓ 即接通。之后在对话里直接说：

• 「查一下 Tripo 余额」

• 「用 Tripo 生成一个 low-poly 小猫的 3D 模型」

• 「把 d:/pic/cat.png 这张图转成 3D 模型」

🛠 9 个工具

📌 模型版本号（易错点）

text_to_3d / image_to_3d 的 model_version 必须是下列有效值之一，写错会报 code 2017 The version value is invalid：

生成一次 text→3D 约消耗 20~60 credits（视面数/版本）。提示词用英文效果最好。

🎮 本地 3D 查看器

生成完直接本地看，不依赖任何外网（three.js 已本地化）。

cd viewer
python serve.py 8000

浏览器开 http://127.0.0.1:8000 → 默认直达旋转鸡块复刻页（彩蛋，见下）；地址加 ?all（即 http://127.0.0.1:8000/?all）进通用查看器：左侧列出 examples/（自带示例）+ output/（你生成的）里的模型，点选即可 360° 旋转、缩放、线框、截图；也可把任意 .glb 拖进去看。

🥚 彩蛋：访问 http://127.0.0.1:8000/nugget 看经典热梗《鸡块旋转四分钟》复刻页（自转 + 大标题 + 计时 + 飘字 + Web Audio 合成 Funky 律动）。

详见 viewer/README.md。

🩺 常见问题

Q: 报 API key must start with 'tsk_' A: Key 前缀不对，去平台重新生成 tsk_ 开头的 Key。

Q: 报 code 2017 The version value is invalid A: model_version 写错了，用上面表格里的有效值之一。

Q: get_balance 返回 0 A: 国内平台（.com）新用户无免费额度。想白嫖走模式 A：注册海外 platform.tripo3d.ai（约 600 credits），配好代理。

Q: 海外站连不上 / DNS 解析到奇怪 IP A: 国内直连 .ai 会被污染。确认梯子开着、HTTPS_PROXY 端口填对、TRIPO_IS_CHINA=false。生成时保持代理在线。

Q: 生成卡住不动 A: 任务在服务端跑，正常 60~180 秒。可另调 get_task(task_id) 单独查。

Q: 注册时验证码收不到 A: 海外站注册需全局邮箱 + 代理 IP 稳定，换节点或换邮箱重试。

🙏 致谢

• 官方 SDK：tripo3d by VAST / Tripo AI

• 3D 渲染：three.js

• 旋转鸡块梗：源自 YouTube CHRISARTS《Nugget SPEENS for 4 Minutes》

📄 License

MIT