poly-pizza-mcp

🚀 Poly.Pizza MCP 服务器

Poly.Pizza MCP 服务器可让你直接将 Poly.Pizza 上的 3D 模型导入到 Unity 项目中。它基于 MCP（Model Context Protocol）协议，为开发者提供了便捷的模型导入解决方案。

✨ 主要特性

• 模型搜索：支持通过关键字在 Poly.Pizza 上搜索 3D 模型。
• Unity 导入：可将搜索到的模型自动导入到 Unity 项目中。
• 批量导入：允许一次性导入多个模型。
• 缓存功能：对下载的模型进行缓存，方便后续重复使用。
• 预制体自动生成：导入模型后，自动生成 Unity 预制体。
• 版权信息自动生成：对于 CC - BY 许可的模型，自动记录版权信息。
• Unity UI 设置 API 密钥：无需设置环境变量，可直接在 Unity 编辑器中输入 API 密钥。

📦 安装指南

1. 安装 Unity 包（通过包管理器）

在 Unity 中，打开 Window > Package Manager，然后：

1. 点击 + 按钮。
2. 选择 Add package from git URL...。
3. 输入以下 URL：

https://github.com/HaD0Yun/poly - pizza - mcp.git?path=unity - package

2. 安装 MCP 服务器

git clone https://github.com/HaD0Yun/poly - pizza - mcp.git
cd poly - pizza - mcp
npm install
npm run build

3. 设置 API 密钥（推荐使用 Unity UI）

1. 在 Unity 中，点击 Window > Poly.Pizza MCP 或 Poly.Pizza > Dashboard 菜单。
2. 点击 Get API Key 按钮，从 poly.pizza/settings/api 获取 API 密钥。
3. 将获取的 API 密钥粘贴到输入框中。
4. 点击 Save API Key 按钮。

API 密钥将保存到 ~/.poly - pizza/config.json 文件中，MCP 服务器会自动读取。

3 - 1. 设置 API 密钥（使用环境变量 - 备用方法）

若要使用环境变量，请执行以下操作：

# Windows
set POLY_PIZZA_API_KEY=your - api - key - here

# macOS/Linux
export POLY_PIZZA_API_KEY=your - api - key - here

4. 配置 MCP 客户端

在 Claude Desktop 或其他 MCP 客户端的配置文件中添加以下内容：

{
  "mcpServers": {
    "poly - pizza": {
      "command": "npx",
      "args": ["-y", "poly - pizza - mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/UnityProject"
      }
    }
  }
}

注意：如果已在 Unity 仪表盘上设置了 API 密钥，则无需在 env 中包含该密钥。

💻 使用示例

基础用法

set_api_key：设置和检查 API 密钥状态

"检查 API 密钥状态"
→ set_api_key()

"设置 API 密钥"
→ set_api_key(apiKey: "your - api - key")

"删除 API 密钥"
→ set_api_key(clear: true)

search_models：在 Poly.Pizza 上搜索模型

"查找汽车模型"
→ search_models(keyword: "car", limit: 10)

import_to_unity：将特定模型导入到 Unity

"将此模型添加到 Unity：5EGWBMpuXq"
→ import_to_unity(modelId: "5EGWBMpuXq", createPrefab: true)

batch_import：批量导入多个模型

"导入所有这些模型"
→ batch_import(modelIds: ["id1", "id2", "id3"])

quick_import：搜索后直接导入第一个结果

"直接导入中世纪剑模型"
→ quick_import(query: "medieval sword")

search_and_batch_import：搜索结果并批量导入

"查找 5 个树木模型并全部导入"
→ search_and_batch_import(keyword: "tree", limit: 5)

get_popular：获取热门模型列表

"最近有哪些热门模型？"
→ get_popular(limit: 20)

cache_status：检查和管理缓存状态

"显示缓存状态" → cache_status(action: "status")
"清除缓存" → cache_status(action: "clear")

📚 详细文档

Unity 项目结构

MCP 服务器导入模型后，文件将按以下结构保存：

Assets/
└── PolyPizza/
    ├── Models/           # 3D 模型文件（.glb、.fbx 等）
    ├── Prefabs/          # 自动生成的预制体
    ├── CREDITS.txt       # 许可证版权信息
    └── .signals/         # MCP 与 Unity 通信使用（自动管理）

Unity 菜单

在 Unity 编辑器中可使用以下菜单：

• Window > Poly.Pizza MCP：设置 API 密钥并打开仪表盘。
• Poly.Pizza > Dashboard：设置 API 密钥并检查状态。
• Poly.Pizza > Refresh Assets：刷新资源。
• Poly.Pizza > Open Models Folder：打开模型文件夹。
• Poly.Pizza > Open Prefabs Folder：打开预制体文件夹。
• Poly.Pizza > Create Prefabs from All Models：从所有模型创建预制体。

许可证信息

Poly.Pizza 的模型提供两种许可证： | 属性 | 详情 | |------|------| | 许可证类型 | CC0、CC - BY | | 署名要求 | CC0 无需署名，CC - BY 必须署名 | | 商业使用 | 两种许可证均允许商业使用 |

使用 CC - BY 许可证的模型时，版权信息将自动记录在 CREDITS.txt 中。游戏发布时，请在版权页面包含这些信息。

🔧 技术细节

开发命令

# 开发模式（监听文件变化）
npm run dev

# 构建项目
npm run build

# 运行项目
npm start

问题解决

API 密钥不工作

• 打开 Unity 中的 Poly.Pizza > Dashboard，检查 API 密钥是否已保存。
• 在 https://poly.pizza/settings/api 检查密钥是否有效。
• 检查 ~/.poly - pizza/config.json 文件是否存在，以及 API 密钥是否正确保存。

Unity 中看不到模型

• 确保 Unity 编辑器已打开。
• 执行 Assets > Refresh 或 Poly.Pizza > Refresh Assets。
• 检查 .signals 文件夹中的文件是否已处理。

缓存问题

• 使用 cache_status(action: "clear") 清除缓存。

📄 许可证

本项目采用 MIT 许可证。

致谢

• Poly.Pizza - 提供免费的低多边形 3D 模型。
• 由 dook（Zac Lucarelli）创建。