MCP 服务器

Tripo CN MCP Server

Integrates Tripo China's 3D AI generation capabilities into the MCP ecosystem, enabling AI agents to create 3D models from text or images, manage tasks, and perform animation pipelines.

README

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

将 Tripo 中国站 3D AI 生成能力无缝接入 MCP 生态

支持 Codex · Claude Code · Cursor · 及所有兼容 MCP 协议的 AI Agent

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

为什么选择 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 调用失败

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

下载失败

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

许可证

MIT

Built with ❤️ for the AI Agent ecosystem