Tripo CN MCP Server

<p align="center"> <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/MCP-1.0+-6E47FF?style=flat-square&logo=anthropic&logoColor=white" alt="MCP"> <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License"> <img src="https://img.shields.io/badge/Tools-25-FF6B35?style=flat-square" alt="Tools"> </p>

<h1 align="center">Tripo CN MCP Server</h1>

<p align="center"> <strong>将 Tripo 中国站 3D AI 生成能力无缝接入 MCP 生态</strong> </p>

<p align="center"> 支持 Codex · Claude Code · Cursor · 及所有兼容 MCP 协议的 AI Agent </p>

---

⚠️ 区域说明：本 Server 仅兼容 Tripo 中国站 API（openapi.tripo3d.com），不兼容国际站（openapi.tripo3d.ai）。API 端点与字段以本文档和 docs/ 目录下的官方 PDF 文档为准。

目录

• 为什么选择 Tripo CN MCP
• 功能概览
• 快速开始
• 环境变量
• MCP 客户端配置
• 典型工作流
• 双 Agent 协作
• 项目结构
• 测试
• 安全
• 故障排查
• 许可证

为什么选择 Tripo CN MCP

将 Tripo 3D 生成 API 封装为标准 MCP Server 后，AI Agent 可以直接调用 3D 生成能力——无需手动编写 HTTP 请求、处理认证、轮询任务状态。一次配置，所有兼容 MCP 的 Agent 即时获得 3D 创作能力。

核心优势：

• 🎯 一键集成：标准 MCP 协议，无需额外适配层
• 🔧 全端点覆盖：25 个工具覆盖 Tripo 全部公开 API
• 🛡️ 安全优先：API Key 防泄漏、SSRF 防护、路径安全检查
• 📦 开箱即用：uv run tripo-cn-mcp 即可启动

功能概览

基于 Tripo 中国站 30 份官方 API 文档完整实现，共 25 个 MCP 工具。

账户与任务管理

工具	功能
tripo_cn_get_balance	查询账户余额与冻结额度
tripo_cn_get_usage	查询账户用量历史
tripo_cn_get_task	查询单个任务状态及结果
tripo_cn_wait_for_task	自动轮询直到任务完成（支持取消）
tripo_cn_batch_get_tasks	批量查询最多 100 个任务

3D 模型生成

工具	功能
tripo_cn_create_text_to_model_task	文本 → 3D 模型（14 个可配置参数）
tripo_cn_create_image_to_model_task	图片 → 3D 模型（支持 file_token / URL / task_id）
tripo_cn_create_multiview_to_model_task	多视图 → 3D 模型（2-8 张图片）

图像生成

工具	功能
tripo_cn_create_text_to_image_task	文本 → 图像
tripo_cn_create_image_to_image_task	图像 → 图像
tripo_cn_create_image_to_multiview_task	图像 → 多视图
tripo_cn_create_edit_multiview_task	编辑多视图输出

模型后处理

工具	功能
tripo_cn_create_texture_task	模型纹理生成 / 重新生成
tripo_cn_create_convert_task	格式转换（glb / fbx / obj / stl / usdz / step / blend / voxel）
tripo_cn_create_segment_task	网格分割
tripo_cn_create_complete_task	网格补全与修复
tripo_cn_create_decimate_task	网格减面

动画管线

工具	功能
tripo_cn_create_rig_check_task	检查模型是否可绑定骨骼
tripo_cn_create_rig_task	骨骼绑定（biped / quadruped 等）
tripo_cn_create_retarget_task	应用预设动画

文件与下载

工具	功能
tripo_cn_upload_file	上传文件获取 file_token（图片 ≤20MB，模型 ≤150MB）
tripo_cn_upload_file_presign	大文件预签名上传（>60MB 推荐）
tripo_cn_download_url	安全 HTTPS 下载（SSRF 防护 + SHA-256 校验）
tripo_cn_download_from_task	从已完成任务自动下载结果

调试工具

工具	功能
tripo_cn_inspect_raw_response	本地分析 API 响应 JSON 结构

快速开始

前置要求

• Python 3.11+
• uv — Python 包管理器

1. 安装 uv

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 克隆项目

git clone https://github.com/<your-username>/tripo-cn-mcp.git
cd tripo-cn-mcp

3. 安装依赖

uv sync --dev

4. 配置环境变量

copy .env.example .env

编辑 .env，填入你的 API Key：

TRIPO_CN_API_KEY=你的_Tripo_中国站_API_Key

5. 启动

uv run tripo-cn-mcp

Server 通过 STDIO 等待 MCP 协议消息，日志输出到 stderr，不干扰协议通信。

环境变量

变量	必填	默认值	说明
TRIPO_CN_API_KEY	✅	—	Tripo 中国站 API Key
TRIPO_CN_BASE_URL	—	https://openapi.tripo3d.com/v3	API Base URL
TRIPO_CN_OUTPUT_DIR	—	~/ExternalGenerated/TripoCN	文件输出目录
TRIPO_CN_REQUEST_TIMEOUT_SECONDS	—	60	HTTP 请求超时（秒）
TRIPO_CN_POLL_INTERVAL_SECONDS	—	5	任务轮询间隔（秒）
TRIPO_CN_MAX_POLL_SECONDS	—	900	最大轮询时间（秒）
TRIPO_CN_LOG_LEVEL	—	INFO	日志级别
TRIPO_CN_ALLOW_UNITY_ASSETS_WRITE	—	false	允许写入 Unity Assets

MCP 客户端配置

Codex

编辑 C:\Users\<用户名>\.codex\config.toml：

[mcp_servers.tripo_cn]
command = 'C:\Users\<用户名>\AppData\Roaming\Python\Python314\Scripts\uv.exe'
args = [
  "run",
  "--project",
  "D:\projects\tripo-cn-mcp",
  "tripo-cn-mcp"
]
startup_timeout_sec = 30
tool_timeout_sec = 900
enabled = true

[mcp_servers.tripo_cn.env]
TRIPO_CN_API_KEY = '你的_API_Key'
TRIPO_CN_OUTPUT_DIR = 'D:\ExternalGenerated\TripoCN'
TRIPO_CN_LOG_LEVEL = 'INFO'

⚠️ 切勿将含有 API Key 的配置提交到 Git。优先使用安全凭据存储。

Claude Code

编辑项目根目录或用户级 .mcp.json，参考 Claude Code MCP 文档 进行配置。

典型工作流

文本生成 3D 模型（最常用）

# 1. 提交生成任务
task = await tripo_cn_create_text_to_model_task(
    prompt="a cute cat wearing a spacesuit",
    model="v3.1-20260211",
    texture=True,
    pbr=True
)
# → {"success": true, "task_id": "task_abc123"}

# 2. 等待完成
result = await tripo_cn_wait_for_task(task_id="task_abc123")
# → {"success": true, "status": "success", "model_url": "https://..."}

# 3. 下载结果
download = await tripo_cn_download_from_task(task_id="task_abc123")
# → {"success": true, "absolute_path": "C:/.../model_abc.glb"}

图片生成 3D 模型 → 动画

# 1. 图片生成模型
img_task = await tripo_cn_create_image_to_model_task(
    input="https://example.com/char.png",
    model="P1-20260311"
)

# 2. 检查可绑定性
rig_check = await tripo_cn_create_rig_check_task(
    input_task_id=img_task.task_id
)
# → riggable: true

# 3. 绑定骨骼
rig_task = await tripo_cn_create_rig_task(
    input_task_id=img_task.task_id,
    rig_type="biped"
)

# 4. 应用动画
anim_task = await tripo_cn_create_retarget_task(
    input_task_id=rig_task.task_id,
    animation="preset:walk"
)

批量查询

batch = await tripo_cn_batch_get_tasks(
    task_ids=["task_abc123", "task_def456"]
)
# → {"success": true, "tasks": {...}, "missed": []}

双 Agent 协作

本 MCP Server 专为美术 Agent 设计，与 Unity 开发 Agent 形成流水线：

美术 Agent                           Unity 开发 Agent
─────────                           ────────────────
tripo-cn-mcp                        Unity MCP
  │ 生成 3D 模型                      │ 导入模型
  ▼                                  ▼
ExternalGenerated/TripoCN  ────►  Assets/ArtGenerated/Staging
  (暂存目录)     人工/自动审核         (临时资源 → 正式 Prefab)

职责分离：

Agent	职责
美术 Agent	调用生成任务、查询状态、下载结果。不操作 Unity 项目
Unity 开发 Agent	读取已审核模型、导入 Unity、创建材质和 Prefab。不重新生成

项目结构

tripo-cn-mcp/
├── pyproject.toml             # 项目配置与依赖声明
├── uv.lock                    # 依赖版本锁定
├── README.md
├── .env.example               # 环境变量模板
├── .gitignore
├── docs/                      # 官方 API 文档（30 份 PDF）+ 架构/安全说明
│   ├── architecture.md
│   ├── security.md
│   ├── api-gap-analysis.md
│   └── codex-config.md
├── src/tripo_cn_mcp/
│   ├── __main__.py            # 入口点
│   ├── server.py              # FastMCP STDIO Server（25 个工具注册）
│   ├── settings.py            # pydantic-settings 配置管理
│   ├── client.py              # httpx AsyncClient 封装（含错误码映射）
│   ├── errors.py              # 13 个自定义异常类
│   ├── models/                # Pydantic 数据模型
│   ├── services/              # 业务逻辑（轮询、下载、路径安全）
│   └── tools/                 # MCP 工具实现（按领域拆分）
└── tests/                     # 84 个测试（全部 Mock，零额度消耗）
    └── fixtures/              # JSON 测试夹具

测试

所有测试均使用 Mock，不会消耗 Tripo API 额度。

# 运行全部测试
uv run pytest

# 代码检查
uv run ruff check .
uv run ruff format --check .
uv run pyright

安全

详见 docs/security.md，核心策略：

策略	说明
🔑 API Key 保护	不出现在日志、异常、MCP 结果中
🌐 SSRF 防护	仅 HTTPS，禁止私有网络访问
📁 路径安全	防路径穿越、防符号链接绕过、同名自动编号
📥 下载安全	流式下载 → 临时文件 → 原子重命名，最大 5GB
🎮 Unity 保护	默认禁止写入 Assets，需显式开启
💰 计费保护	测试全部 Mock，零额度消耗
🚫 无 Shell 执行	不调用 eval() / exec() 或系统命令

暂存目录

~/ExternalGenerated/TripoCN/
├── model_abc.glb              # 生成结果
├── model_abc_1.glb            # 同名自动编号
└── tripo_download_*.tmp       # 下载临时文件（自动清理）

故障排查

Server 无法启动

# 检查依赖
uv sync --dev

# 验证配置（不显示完整 API Key）
uv run python -c "from tripo_cn_mcp.settings import Settings; s=Settings(); print('OK:', s.masked_dict())"

API 调用失败

1. 确认 TRIPO_CN_API_KEY 已正确设置
2. 检查网络是否能访问 openapi.tripo3d.com
3. 提高日志级别：TRIPO_CN_LOG_LEVEL=DEBUG
4. 使用 tripo_cn_inspect_raw_response 调试响应结构

下载失败

• 确认 URL 以 https:// 开头
• 检查输出目录是否可写
• 检查磁盘剩余空间
• 模型 URL 有效期仅 5 分钟，请及时下载

许可证

MIT

---

<p align="center"> _{Built with ❤️ for the AI Agent ecosystem} </p>