game-asset-mcp

一个 MCP 服务器，让 AI 代理能够端到端地生成可用于游戏的 3D 资产——参考图像、网格、PBR 纹理、来源信息——并为你已经拥有的网格重新贴图。

大多数资产生成工具止步于“输入提示词，获得网格”。那是容易的一半。真正阻碍项目的另一半是你已经拥有的网格：你上周建模的 kitbash、材质不符合你美术方向的市场道具、需要在周五前看起来像腐蚀钢的灰盒。texture_existing_asset 接受你提供的网格，并为其赋予新的 PBR 材质，而不会重新生成你已经批准的几何体。

一切都会被记录。每个任务都会保留提示词、种子、提供商模型版本、提供商任务 ID，以及每个下载字节的 SHA-256——这样六个月后你仍然能回答“这个文件是什么产生的？”

该服务器在设计上不依赖特定提供商。目前它驱动 Tripo 用于 3D，Leonardo.Ai 用于参考图像和音效，背后是三个小接口（ImageProvider、Model3DProvider、AudioProvider）。添加提供商不会改变工具表面。参见 docs/architecture.md 了解为何如此构建。

要求

• Node.js >= 18.17 — 服务器使用全局 fetch、FormData、Blob 和 AbortController。

• 无需原生模块、无需构建工具链、无需数据库。它可以在任何运行 Node 的地方运行。

• 可选： 本地安装 Blender 4.x+ 可启用 normalize_mesh 和 batch_prepare_meshes 的修复功能。其他所有工具无需它即可工作；当它缺失时，工具会拒绝并给出说明。在 macOS 上，Blender 不在 PATH 中，因此请设置 BLENDER_PATH 或依赖捆绑的 /Applications/Blender.app 默认值。

• 至少一个提供商 API 密钥（参见 配置）。一个就足够了——它们是惰性验证的。

Related MCP server: Context3D MCP Server

安装

直接从 GitHub 安装。两种形式都会在安装时构建 TypeScript，因此无论哪种方式你都能获得可运行的 game-asset-mcp 二进制文件。

# run it without installing anything permanently
npx github:theisegoria/game-asset-mcp

# or add it to a project
npm install github:theisegoria/game-asset-mcp

# pin a specific version — recommended for anything you depend on
npm install github:theisegoria/game-asset-mcp#v0.3.8

固定版本。 如果没有 #vX.Y.Z 后缀，两种形式都会解析为当时 main 分支的内容，这不是稳定的依赖。每个版本都有标签，因此 #v0.3.8 会精确地给你那个树。版本列表见 github.com/theisegoria/game-asset-mcp/releases，每个版本都附带了该版本修复的缺陷。

⛔ 不要固定 v0.3.0、v0.3.1 或 v0.3.2。 后续审查发现这些版本中存在会破坏你传入的网格并报告成功的活动路径。它们被标记只是为了历史完整。它们的发布页面也说明了这一点。

或者从克隆版本开始，如果你想修改任何内容，这是你想要的：

git clone https://github.com/theisegoria/game-asset-mcp.git
cd game-asset-mcp
npm install
npm run build     # emits dist/
node dist/server.js

不在 npm 上。 没有 npm install @theisegoria/game-asset-mcp——该包仅从 GitHub 分发。任何其他说法都已过时。

服务器通过 stdio 进行 MCP 通信。直接在终端中启动它，它会静静地等待客户端与之通信——这是正确行为，不是挂起。日志输出到 stderr；stdout 属于协议。

配置

在你的 MCP 客户端的 env 块中设置这些——参见下面的代码片段。没有 .env 加载：服务器只读取 process.env，不读取其他内容，因此磁盘上的 .env 文件除非你的 shell 或客户端先导出它，否则不起作用。

⚠️ Tripo API 信用与 Tripo Studio 订阅分开计费

这几乎会坑到所有人。Tripo Studio 网页订阅不会为 API 调用提供资金。 它们是两个不同的产品，有两个不同的余额。如果你一直在 Studio 网页应用中愉快地生成模型，而你的第一次 create_3d_asset 调用因信用不足而被拒绝，那么你没有配置错误——你需要在开发者平台上购买 API 信用。请在 platform.tripo3d.ai 购买，而不是在 Studio 应用中。

限制可花费的金额

设置 ASSET_SPEND_LIMIT_CENTS 后，每个消耗信用的工具都会在联系提供商之前检查它——包括在上传网格或参考图像之前——拒绝时会指明剩余余额，而不是超支。上限以美分为单位，因为两个提供商以不同单位计费——Tripo 以 $0.01 信用计费，Leonardo 以美元计费——混合使用它们的限额将毫无意义。

如果提供商公布了每次调用的价格，我们会使用它。如果没有，守卫会使用一个故意保守的占位值，get_spend_report 会说明哪些数字是哪种。它是一个守卫，不是发票：实际费用应等于或低于估计值，绝不会高于。

一个提供商就足够了

凭据是惰性验证的，在工具需要它们时才验证，绝不会在启动时验证。如果你只设置了 TRIPO_API_KEY，服务器会正常启动，所有 3D 工具都能工作；图像工具会返回一个明确的 CONFIG_MISSING 错误，指出你缺少的变量。反之亦然。你永远不会被迫持有你不想要的账户，只为了使用你想要的管道的一半。

MCP 客户端设置

Claude Code / Claude Desktop

添加到你的 MCP 配置中（claude_desktop_config.json，或 Claude Code 项目中的 .mcp.json）：

{
  "mcpServers": {
    "game-asset": {
      "command": "node",
      "args": ["/absolute/path/to/game-asset-mcp/dist/server.js"],
      "env": {
        "TRIPO_API_KEY": "tsk_...",
        "LEONARDO_API_KEY": "...",
        "ASSET_OUTPUT_DIR": "/absolute/path/to/your/project/assets/generated",
        "ASSET_LOG_LEVEL": "info"
      }
    }
  }
}

对 args 和 ASSET_OUTPUT_DIR 使用绝对路径。MCP 客户端的工作目录不是你想的那个，相对输出目录会把资产散落到意想不到的地方。

任何其他 MCP 客户端

同一个服务器，通用描述——一个 stdio 子进程：

{
  "name": "game-asset",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "github:theisegoria/game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

可用工具

只有九个工具会花费你的钱，每个工具的描述中都在被调用前明确说明了这一点。

免费的本地部分（无需 API 密钥，无需网络）

二十个工具中有十一个从不消耗积分，而其中只有两个会使用网络——get_asset_job 用于轮询，download_asset 用于获取；两者都免费但属于网络调用。其余九个可离线工作。下面五个是网格管线，如果你已有网格，它们就是全部产品。

通常的循环是 validate → normalize → validate again，这样修复是被证明的而非假设的：

validate_game_asset  modelPath=/art/crate.glb
   → fails: uvs_present   ("nothing can texture this")
normalize_mesh       modelPath=/art/crate.glb  outputDir=/art/out
   → objectsUnwrapped=2, triangles 3183 → 1750
validate_game_asset  modelPath=/art/out/crate_normalized.glb
   → passes

batch_prepare_meshes 对列表运行该循环并逐项报告。已通过的网格保持不变而非重写，单个坏文件绝不会中断运行，两个共享相同基名的源会得到不同的输出而非互相覆盖。

缺少 UV 是最值得了解的缺陷。 没有 UV 坐标的网格无法被任何工具贴图——不是这个工具，不是提供方，也不是你手动操作。生成器和市场资产经常不带 UV 就发布。validate_game_asset 因此将其列在首位。

规范化需要 Blender（4.x+）。没有它，工具仍可验证和报告，只是无法修复。在 macOS 上 Blender 不在 PATH 中，因此要么设置 BLENDER_PATH，要么依赖自带的 /Applications/Blender.app 默认路径。

示例工作流

完整管线：从想法到已检查的资产

1. generate_asset_reference   → spends image credits, returns assetJobId + N candidates
2. (inspect the images)       → look at the returned reference images and choose one
3. select_reference           → free; records which candidate wins
4. create_3d_asset            → spends 3D credits, returns a task to poll
5. get_asset_job              → free; poll until status is "ready" (or "failed")
6. download_asset             → free; pulls model + textures + previews into the workspace
7. inspect_asset              → free; confirms what actually landed on disk

第 2 步不是装饰。在花费 3D 积分之前选择参考图，正是管线在此处拆分的原因：糟糕的参考图会产生融化的网格，而你只有在支付重建费用之后才会发现。

重新贴图：更短、更便宜，也是大多数工具没有的流程

你已经拥有网格。无需参考、无需选择、无需重建：

1. texture_existing_asset     → spends texturing credits on a mesh you supply
2. get_asset_job              → free; poll until ready
3. download_asset             → free
4. inspect_asset              → free

一次付费调用而非两次，而且你已批准的几何体会原样返回。

费用与副作用

消耗提供方积分的调用： generate_asset_reference、generate_reference_variations、create_3d_asset、texture_existing_asset、generate_sound_effect、rig_asset、animate_asset、retopologize_asset，以及 create_game_prop 内部的图像生成步骤。此服务器中的其他任何操作都不会产生费用。

免费的调用： select_reference、get_asset_job、download_asset、inspect_asset、list_asset_jobs、preview_asset_prompt、extract_pbr_trio、normalize_mesh、validate_game_asset、batch_prepare_meshes、get_spend_report。想轮询、检查、拆分和下载多少次都可以。

消耗额度的 POST 请求绝不会自动重试。 这是一条深思熟虑、承重墙级别的规则，它位于 HTTP 层，而不是每个调用点。当一个创建生成任务的请求失败时——超时、socket 重置、502——客户端无法判断提供方是否在连接断开前接受了该请求。重试可能是免费的；也可能让你为一个从未收到的网格付双倍费用。所以它不会重试，错误会直接返回，是否再次尝试的决定权在你。幂等读取——状态轮询、文件下载——可以带退避自由重试，因为重复执行它们不产生任何成本。

其他值得了解的副作用：

• 文件会写入磁盘。 下载的资产落在 ASSET_OUTPUT_DIR 下，任何逃逸出工作区根目录的下载路径都会被拒绝。有三个工具不同，且是刻意为之：extract_pbr_trio、normalize_mesh 和 batch_prepare_meshes 写入你指定的位置，包括工作区之外，因为它们操作的是你已经拥有的网格，而这些网格并不存在于资产生成目录中。给它们一个你确实想要的目标位置。

• download_asset 和 generate_sound_effect 接受 destination，它仅对这一次调用覆盖 ASSET_OUTPUT_DIR。它仍然受约束：逃逸出给定根目录的路径会被拒绝。

• ASSET_OUTPUT_DIR 应为绝对路径。 相对值会相对于服务器的工作目录解析，而该目录由你的 MCP 客户端决定——有几个客户端从 / 启动。服务器会拒绝启动，并给出一条消息，指明解析出的路径及其来源的工作目录。这一诊断覆盖了此问题实际可能产生的八种 errno——ENOENT、EACCES、EPERM、EROFS、ENOTDIR、ELOOP、ENAMETOOLONG 和 ENOSPC，包括 ASSET_OUTPUT_DIR 指向文件而非目录的情况。其他任何错误仍然原样传播。

• 没有任何内容会被静默覆盖。 派生的输出名称会获得数字后缀（crate、crate_2、……），而不是销毁你可能已经审阅过的结果，并且该名称通过独占创建来认领，因此同一批次中的两个条目不会争抢它。显式的 outputPath 在文件已存在时会被直接拒绝，除非你传入 overwrite: true——而如果它解析到输入网格上，则无条件拒绝，没有任何退出选项。该解析会考虑符号链接、硬链接、大小写不敏感的卷，以及导出器重写扩展名的习惯，因为这里的每一种情况都曾毁掉过源网格。

• 下载有上限，为 ASSET_MAX_DOWNLOAD_BYTES，且上限在流式传输过程中强制执行，而不是依据 Content-Length 头——一个谎报大小的服务器无法耗尽你的内存。

• 仅限 HTTPS。 非 HTTPS 的 URL 会被直接拒绝，包括出现在提供方响应中的那些。

• API 密钥会在日志中被集中脱敏，因此任何单独的日志调用点都无法泄露密钥。

工作区布局

每个资产都有一个自包含的目录。六个月后在文件浏览器中打开它，它仍然能自我解释：

assets/generated/
├── .jobs/                          job records, one JSON file per job
│   └── asset_<uuid>.json
└── <asset_name>/
    ├── asset.json                  complete provenance: spec, prompt, seed,
    │                               model version, provider ids, file hashes
    ├── source/                     the reference image(s) the mesh was built from
    ├── model/                      the mesh (GLB by default)
    ├── textures/                   extracted PBR maps
    ├── previews/                   provider-rendered turnarounds

<asset_name> 是你的 spec 名称经过清理后的结果：小写化，非字母数字字符折叠为下划线。.jobs 目录刻意做成点目录——浏览你的资产工作区时应该看到资产，而不是簿记文件。

故障排查

每个错误都携带一个机器可读的 error 字段，指明错误类别，外加一个 retryable 标志，这样代理无需解析文字就能决定下一步做什么。下面的名称就是该 error 字段的值。

服务器启动后立即退出——客户端只显示"连接已关闭"。 三个已知原因，服务器现在会自行指明前两个，而不是静默死亡。

• 相对路径的 ASSET_OUTPUT_DIR。 它相对于服务器的工作目录解析，而该目录由你的 MCP 客户端选择——有几个从 / 启动，于是 assets/generated 变成 /assets 且无法创建。请使用绝对路径。 拒绝消息会指明解析出的路径及其来源的工作目录。

• 进程无法写入的工作区。 同样的拒绝，不同的 errno。

• 过期的构建。 如果 dist/ 早于入口点的变更，请重新构建。npm run verify 会构建并随后完成一次真实的 MCP 握手，这是区分服务器坏了还是客户端配置坏了的最快方式。

normalize_mesh 或 batch_prepare_meshes 以"未找到 Blender"拒绝。 PATH 上没有本地 Blender。在 macOS 上，即使安装了 Blender，应用包也不在 PATH 上——请将 BLENDER_PATH 设置为包内的可执行文件。batch_prepare_meshes 会降级而不是失败：它仍然验证每个网格，并报告需要修复的内容。

CONFIG_MISSING——缺少凭据。 你调用的工具需要你尚未配置的提供方。消息会指明确切的环境变量。在你的 MCP 客户端的 env 块中设置它，然后重启客户端。.env 文件永远不会被读取：没有 dotenv 依赖，因此该变量必须由启动服务器的任何进程导出。

PROVIDER_HTTP 且状态码为 401/403——API 密钥无效。 密钥错误、已被吊销，或者是错误提供方的密钥。两个具体的陷阱：Leonardo 密钥需要在账户上启用 API 访问（仅网页登录并不授予此权限）；而 Tripo 密钥如果没有 API 额度余额，可能在第一次付费调用时就失败，即使密钥本身是有效的。参见上面的额度警告。

RATE_LIMITED——HTTP 429。 标记为可重试。轮询会退避并自动重试（400 毫秒、800 毫秒、1600 毫秒，上限 8 秒）。下载不会重试——download_asset 单次尝试流式下载，所以请自行重新发起；由于提供方 URL 会过期，请先用 get_asset_job 重新轮询，而不是重试过期的 URL。生成请求也不会重试，这是刻意的，因为它们花钱。下载期间的 429 会以状态码为 429 的 PROVIDER_HTTP 形式出现，而不是 RATE_LIMITED。

PROVIDER_TASK_FAILED——任务在提供方侧失败。 HTTP 调用成功了，但生成没有。提供方自己的消息会保留在错误详情中。审核拒绝也会落在这里：请重写提示词，而不是原样重试。注意，Tripo 的响应可能携带 HTTP 200 但信封 code 非零；那是一次失败，本服务器会将其视为失败，而不是报告虚假的成功。

下载以 PROVIDER_HTTP 403/404 失败——URL 已过期。 这是最常见的意外。提供方的模型和预览 URL 是短命的。 它们经过签名、会过期，二十分钟前还能用的 URL 现在已经失效。解决办法不是重试同一个 URL——而是再次调用 get_asset_job 向提供方重新轮询获取新 URL，然后立即 download_asset。养成习惯：任务一报告 ready 就立即下载，而不是在漫长的会话结束时才下载。

INVALID_INPUT——不支持的图像格式。 参考图像应为标准的 Web 安全栅格格式（PNG、JPEG、WebP）。HDR、EXR、分层 PSD、SVG 和多页 TIFF 都是不可重建的输入。对于 texture_existing_asset，网格必须是 GLB、GLTF、FBX、OBJ 或 STL。请先转换；提供方不会替你转换。

PROVIDER_MALFORMED_RESPONSE——提供方返回了意外内容。 非 JSON 的响应体、空信封、无数据的成功，或上传未返回文件令牌。通常意味着提供方侧的事故或 API 版本漂移。设置 ASSET_LOG_LEVEL=debug 以查看请求形状（密钥已脱敏），并在假设 bug 在本地之前先查看提供方的状态页面。

DOWNLOAD_TOO_LARGE。 文件超过了 ASSET_MAX_DOWNLOAD_BYTES。高质量的 PBR GLB 可能很大；如果你确实想要该文件，请提高限制。

PATH_ESCAPE。 提供方提供的文件名试图解析到你的工作区之外。写入已被拒绝。这在正常操作中不应发生——如果发生了，请提交 issue。

状态

这是早期软件，最可能漂移的部分都被明确标注，而不是被默默假定。

Tripo 的 v3 端点路径被固定在一个模块中（src/providers/model3d/tripo.ts），并在其顶部以注释形式记录。Tripo 的公开文档以两种不同的方式描述 v3 接口——一个通用任务端点和按操作划分的路径——两者都出现在当前文档中。本客户端实现的是任务形式，这与可观察到的行为一致，即每次生成都会返回一个 task_id 供轮询，并暴露 TRIPO_BASE_URL 以便无需编辑代码即可重新定向。如果它们错了，你会看到一个看起来完全像 API 密钥错误的 404，所以先检查路径，再检查密钥。

从未对真实提供方 API 发起过任何调用。 这是这里最重要的注意事项，所以直说而不埋没。394 个测试中的每一个都针对 mock 或本地文件系统运行。它们覆盖了提示词构建、状态映射、路径安全、任务存储、HTTP 层的重试和重定向规则，以及针对真实文件的 glTF 检查——但一套全绿的测试套件并不能说明 Leonardo 和 Tripo 的行为是否如本客户端所假设的那样。

具体来说，以下内容仍然未经验证：

• 上述 Tripo v3 端点路径。

• texture_model 是否接受上传的网格（file_token），还是只接受先前 Tripo 任务产生的网格（original_model_task_id）。这决定了你是否能重新纹理自己已有的模型，而这正是本服务器存在的意义。解决它需要一次 HD 纹理调用的成本。

• 音效生成未经验证。 Leonardo 记录了 Sound Effects v2 请求契约（model、prompt、duration 1-22 秒、prompt_influence、loop、quantity），但没有记录其响应形状或成品音频的获取方式。客户端从几种看似合理的形状中读取生成 id 和音频 URL，当都不匹配时，会抛出带有响应顶层键名（而非响应体，响应体可能很大或携带签名 URL）的错误，而不是报告空成功。预计第一次真实调用需要修复，请附上你看到的载荷形状提交 issue。

• src/providers/image/leonardo.ts 中的 Leonardo 模型 id，它们是从已发布的文档转录的。请对照 GET /platformModels 检查；过期的 id 会以 HTTP 400 失败，读起来像格式错误的请求体。LEONARDO_MODEL_ID 和每次调用的 modelId 都作为逃生舱存在。

如果你是第一个用真实密钥运行它的人，请准备好修复端点路径，并请提交 issue 说明你发现的内容。

已验证的内容： npm run verify 构建服务器，通过 stdio 用真实的 MCP 客户端启动它，完成握手并断言全部二十个工具都已注册。这是一次协议往返，而不是版本字符串——一个未能注册其工具的服务器仍然可以非常愉快地启动。

本地流水线的部分——inspect_asset、extract_pbr_trio、normalize_mesh、validate_game_asset——还额外针对真实发布的游戏资产而非 fixture 进行检查，因为合成 fixture 和读取它的解析器可能共享同一个错误，并且两者看起来都是绿的。这里就发生过：一个错误的 glTF 魔数常量通过了整套合成测试套件，只有真实文件才捕获了它。它们使用的无 UV 网格已提交在此处，而不是从兄弟 checkout 中读取。它过去是从游戏仓库实时读取的，当该网格被修复时，这些测试因为一个完全正确的变更而变红——一个断言固定了本项目不控制的文件的事实。测试不得依赖它不拥有的内容。

有一项测试通过符号链接的 bin（即 node_modules/.bin 实际包含的内容）来启动构建后的服务器，并与它进行 MCP 通信，因为入口点守卫正是在这里失败的：服务器在每次安装时都会立即退出，却通过了所有其他测试。它采用符号链接而非安装方式，因此无法捕获 files 或 prepare 中的打包回归；从 GitHub 进行真正的 npm install 仍然需要手动检查。

为什么测试数量不是重点

在 0.3.4 中，上一个版本的五项主要修复被逐一还原并重新运行测试套件。五项全部存活——每个变异体都完全通过。 这些修复是真实的；套件中没有任何东西在约束它们。原因是一个共同的假设：每个被桩化的 Blender 都以退出码 0 结束并恰好打印一份回执，因此子进程协议的加固在任何测试中都无法被观察到。

这值得在 README 中说明，因为这是对任何测试数量（包括本项目的测试数量）的诚实解读。测试套件验证的是作者的假设，而存在于假设内部的缺陷，对在该假设下编写的所有测试都是不可见的。改变的是纪律，而不是数量：修复现在由针对还原后的代码运行并观察到失败的测试所固定，共享的假对象被视为嫌疑对象而非基础设施。

同样的检查在一次操作中两次捕获了错误的证明。为证明焊接阈值修复而编写的两个连续夹具，在代码正确和代码损坏时报告了相同的三角形数量，而任何一个都可能作为证据发布。夹具只有在同时通过修复后和损坏的代码运行并打印出两个数字之后，才能算作证明。

贡献

欢迎提交 issue 和 pull request。如果你要添加提供者，请实现 ImageProvider 或 Model3DProvider 并且不要改动其他任何内容——如果新的提供者迫使工具表面发生变化，说明抽象有误，而这正是值得首先讨论的 bug。

许可证

MIT © 2026 Ben Haire。参见 LICENSE。