Poly Pizza MCP

🚀 Poly.Pizza MCP Server

The MCP (Model Context Protocol) server that allows you to directly import Poly.Pizza 3D models into your Unity projects.

✨ Features

• Model Search: Search for 3D models on Poly.Pizza using keywords.
• Unity Import: Automatically import the searched models into your Unity projects.
• Batch Import: Import multiple models at once.
• Caching: Cache downloaded models for reuse.
• Automatic Prefab Generation: Automatically create Unity Prefabs from imported models.
• Automatic Credit Generation: Automatically record credits for CC-BY licensed models.
• API Key Setup in Unity UI: Enter your API key directly in the Unity editor without using environment variables.

📦 Installation

1. Install the Unity Package (Package Manager)

Open Window > Package Manager in Unity and:

1. Click the + button.
2. Select Add package from git URL...
3. Enter the following URL:

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

2. Install the MCP Server

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

3. Set the API Key (Using Unity UI - Recommended)

1. Click the Window > Poly.Pizza MCP or Poly.Pizza > Dashboard menu in Unity.
2. Click the Get API Key button to obtain an API key at poly.pizza/settings/api.
3. Paste the obtained API key into the input field.
4. Click the Save API Key button.

The API key is stored in ~/.poly-pizza/config.json and will be automatically read by the MCP server.

3-1. Set the API Key (Using Environment Variables - Alternative)

If you want to use environment variables:

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

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

4. Configure the MCP Client

Add the following to the configuration file of Claude Desktop or other MCP clients:

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

Note: If you have set the API key in the Unity Dashboard, you don't need to include it in env.

💻 Usage Examples

Basic Usage

Available Tools

set_api_key

Set and check the status of the API key.

"Check the API key status."
→ set_api_key()

"Set the API key."
→ set_api_key(apiKey: "your-api-key")

"Delete the API key."
→ set_api_key(clear: true)

search_models

Search for models on Poly.Pizza.

"Find car models."
→ search_models(keyword: "car", limit: 10)

import_to_unity

Import a specific model into Unity.

"Add this model to Unity: 5EGWBMpuXq."
→ import_to_unity(modelId: "5EGWBMpuXq", createPrefab: true)

batch_import

Import multiple models at once.

"Import all these models."
→ batch_import(modelIds: ["id1", "id2", "id3"])

quick_import

Immediately import the first result after a search.

"Immediately import a medieval sword model."
→ quick_import(query: "medieval sword")

search_and_batch_import

Batch import all search results.

"Find 5 tree models and import them all."
→ search_and_batch_import(keyword: "tree", limit: 5)

get_popular

View the list of popular models.

"What are the popular models these days?"
→ get_popular(limit: 20)

cache_status

Check and manage the cache status.

"Show the cache status." → cache_status(action: "status")
"Clear the cache." → cache_status(action: "clear")

📚 Documentation

Unity Project Structure

When the MCP server imports models, they are saved in the following structure:

Assets/
└── PolyPizza/
    ├── Models/           # 3D model files (.glb, .fbx, etc.)
    ├── Prefabs/          # Automatically generated prefabs
    ├── CREDITS.txt       # License credits
    └── .signals/         # For MCP ↔ Unity communication (automatically managed)

Unity Menus

Menus available in the Unity Editor:

• Window > Poly.Pizza MCP: Set the API key and view the dashboard.
• Poly.Pizza > Dashboard: Set the API key and check the status.
• Poly.Pizza > Refresh Assets: Refresh the assets.
• Poly.Pizza > Open Models Folder: Open the model folder.
• Poly.Pizza > Open Prefabs Folder: Open the prefab folder.
• Poly.Pizza > Create Prefabs from All Models: Create prefabs from all models.

License Information

Poly.Pizza models are provided under two licenses:

When using CC-BY licensed models, credits are automatically recorded in CREDITS.txt. Please include this content on the credits screen when releasing your game.

Development

# Development mode (watch)
npm run dev

# Build
npm run build

# Run
npm start

Troubleshooting

The API key is not working

• Open Poly.Pizza > Dashboard in Unity and check if the API key is saved.
• Check if the key is valid at https://poly.pizza/settings/api.
• Check if the ~/.poly-pizza/config.json file exists and the API key is saved correctly.

Models are not visible in Unity

• Check if the Unity Editor is open.
• Run Assets > Refresh or Poly.Pizza > Refresh Assets.
• Check if the files in the .signals folder have been processed.

Cache issues

• Initialize the cache using cache_status(action: "clear").

📄 License

MIT

Credits

• Poly.Pizza - Free low poly 3D models
• Created by dook (Zac Lucarelli)