Hunyuan 3D MCP

通过 MCP 为 Codex、Claude Code、Cursor 提供腾讯混元生 3D 的模型生成及后处理服务。本项目是社区集成，使用你自己的腾讯云凭据。

安装 Codex 插件

要求：Codex（支持 codex plugin）、Git、uv，以及 Python 3.11+。所有服务使用腾讯云 TC3，需要 SecretId/SecretKey。将凭据设置在启动 Codex 的环境中：

# 纹理、组件、极速版、UV、减面、绑骨、动作等服务需要：
export TENCENTCLOUD_SECRET_ID='你的 SecretId'
export TENCENTCLOUD_SECRET_KEY='你的 SecretKey'
codex plugin marketplace add <仓库地址>
codex plugin add hunyuan3d@hunyuan3d

本地开发版本：

codex plugin marketplace add .
codex plugin remove hunyuan3d@hunyuan3d
codex plugin add hunyuan3d@hunyuan3d

重启会话后调用 hy3d_check_config 检查配置。插件使用安装副本中的 uv.lock 和独立环境启动，与你启动 Codex 时激活的 Python 环境无关；首次启动会下载依赖。

Related MCP server: openscad-mcp

独立 MCP

uv tool install ./plugins/hunyuan3d
hunyuan3d-mcp --check-config

把 hunyuan3d-mcp 配置为任意 STDIO MCP 客户端的 command，并转发腾讯云凭据环境变量。服务提供 15 个按用途划分的服务工具（共 19 个工具），另有能力发现、配置检查和任务查询工具。

服务工具与调用流程

Agent 可以直接通过 MCP 工具描述和参数 schema 选择服务，不需要猜测通用提交接口的参数。 hy3d_list_capabilities 会提供调用示例、凭据要求、动作预设和人物模板。

业务参数直接放在顶层，例如 {"prompt":"一把椅子","model":"3.1"}，不再使用 request 包装或提交时的 backend 参数；image、file 等保留结构化对象。 多视角生成使用独立工具，必填主图 image 和 1–7 张额外视图 multi_view_images， 默认模型 3.1。同一角度不可重复；3.0 仅支持额外的左、右、后视图。 原先向单图工具传额外视图的调用应迁移到多视角工具。

生成工具返回 JobId、service、backend，以及可直接复制给 hy3d_query_job 或 hy3d_wait_job 的参数。完成后可以把结果模型 URL 传给纹理、组件等后续工具。 格式转换直接返回 URL，不需要轮询。所有服务统一使用腾讯云 TC3。

**鉴权：**所有服务使用腾讯云 TC3，需要 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY；临时凭据还需 TENCENTCLOUD_TOKEN。 所有凭据仅从运行环境读取；hy3d_check_config 可检查哪些服务已具备凭据。

图片支持 URL、绝对路径或 Base64；已有模型需提供腾讯可访问的 URL。组件生成只接受 FBX， 可先调用格式转换工具。完整参数、限制和串联示例见 插件使用说明。

MCP Inspector 调试

安装 Node.js 后，可以使用官方 MCP Inspector 调试独立运行的 STDIO 服务。先安装命令并设置腾讯云凭据：

uv tool install ./plugins/hunyuan3d
# 纹理、组件、极速版、UV、减面、绑骨、动作等服务需要：
export TENCENTCLOUD_SECRET_ID='你的 SecretId'
export TENCENTCLOUD_SECRET_KEY='你的 SecretKey'

从项目根目录启动 Inspector：

npx @modelcontextprotocol/inspector hunyuan3d-mcp

Inspector 会启动本地代理并打开 Web UI。在 UI 的 Tools 页面可以查看工具、填写参数并调用，也可以查看初始化、请求和响应日志。服务通过 STDIO 与 Inspector 通信，请勿向标准输出写入日志；结束调试时在终端按 Ctrl-C。如需只验证配置，可运行 hunyuan3d-mcp --check-config。

开发检查

uv run --project plugins/hunyuan3d --locked python -m pytest
uv run --project plugins/hunyuan3d --locked ruff check .

开发约定和发布流程见 AGENTS.md。