mcp-game-asset-gen
Asset generation MCP server for Three.js and game engines
Open source Open in the app JSON README (API)
About
Asset generation MCP server for Three.js and game engines
Details
- Kind
- Plugins
- Topic
- Media, design & games
- Publisher
- flux159
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 21
- Forks
- 6
- Open pull requests
- 1
- Last push
- 2025-12-06T20:07:04Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
flux159/mcp-game-asset-gen
README
# MCP Asset Generation Server
<img width="1645" height="1034" alt="Screenshot 2025-11-09 at 9 15 04 AM" src="https://github.com/user-attachments/assets/d2bc7cda-8a09-4588-b3c8-7f430cfde2ee" />
A Model Context Protocol (MCP) server for generating various types of assets including images, videos, audio, and 3D models for game development.
Three.js sample scene in [demo video](https://www.youtube.com/watch?v=KSVpJFqF5hg) located at [flux159/three-generator](https://github.com/Flux159/three-generator).
## Features
- **Image Generation**: Support for multiple providers (OpenAI DALL-E, Google Gemini, Fal.ai)
- **Video Generation**: Coming soon
- **Audio Generation**: Coming soon
- **3D Model Generation**: Generate 3D models using FAL.ai Trellis and Hunyuan3D 2.0
- **Game Development Focus**: Optimized for creating game assets
## Installation
```bash
# Clone the repository
git clone <repository-url>
cd mcp-game-asset-gen
# Install dependencies
npm install
# Build the project
npm run build
```
## Development
```bash
# Run in development mode with hot reload
npm run dev
# Run tests
npm test
# Run tests with UI
npm run test:ui
# Type checking
npm run typecheck
# Linting
npm run lint
```
## Usage
The server provides tools and prompts for asset generation through the MCP protocol.
### Available Tools
#### Image Generation
- `openai_generate_image`: Generate images using OpenAI's image generation API
- Parameters:
- `prompt` (required): Detailed description of the image to generate
- `outputPath` (required): Path where the generated image should be saved
- `inputImagePath` (optional): Path to input image for editing/variation
- `size` (optional): Image dimensions ('1024x1024', '1792x1024', '1024x1792')
- `quality` (optional): Image quality level ('standard', 'hd')
- `style` (optional): Image style preference ('vivid', 'natural')
- `n` (optional): Number of images to generate (1-10)
- `gemini_generate_image`: Generate images using Google's Gemini native image generation (supports 2.5 Flash and 3 Pro models)
- Parameters:
- `prompt` (required): Description of the image to generate
- `outputPath` (required): Path where the generated image should be saved
- `inputImagePaths` (optional): Array of paths to input images for variation/combination
- `model` (optional): Gemini model to use ('gemini-2.5-flash-image', 'gemini-3-pro-image-preview', default: gemini-3-pro-image-preview)
- `falai_generate_image`: Generate high-quality images using FAL.ai's Qwen image generation model
- Parameters:
- `prompt` (required): Detailed prompt for image generation
- `outputPath` (required): Path where the generated image should be saved
- `image_size` (optional): Image size preset ('square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9')
- `num_inference_steps` (optional): Number of inference steps (1-50)
- `guidance_scale` (optional): How closely to follow the prompt (1-20)
- `falai_edit_image`: Edit images using FAL.ai's Qwen image editing model
- Parameters:
- `prompt` (required): Detailed prompt describing the desired edits
- `inputImagePath` (required): Path to input image to be edited
- `outputPath` (required): Path where the edited image should be saved
- `image_size` (optional): Image size preset
- `num_inference_steps` (optional): Number of inference steps (1-50)
- `guidance_scale` (optional): How closely to follow the prompt (1-20)
#### Game Asset Generation
- `generate_character_sheet`: Generate character sheets from text descriptions or reference images
- Parameters:
- `characterDescription` (required): Detailed description of the character
- `outputPath` (required): Path where the character sheet should be saved
- `referenceImagePaths` (optional): Array of reference image paths (character, outfit, etc.)
- `model` (optional): Model to use for generation ('openai', 'gemini', 'falai', default: gemini - uses gemini-3-pro-image-preview)
- `style` (optional): Art style for the character sheet (e.g., anime, realistic, cartoon)
- `includeExpressions` (optional): Include multiple facial expressions
- `includePoses` (optional): Include multiple poses/angles
- `generate_character_variation`: Generate character variations by combining reference images
- Parameters:
- `prompt` (required): Description of the variation to create
- `outputPath` (required): Path where the variation should be saved
- `referenceImagePaths` (required): Array of reference image paths to combine
- `model` (optional): Model to use for generation ('openai', 'gemini', 'falai', default: gemini - uses gemini-3-pro-image-preview)
- `generate_pixel_art_character`: Generate pixel art characters with specific dimensions for retro games
- Parameters:
- `characterDescription` (required): Description of the pixel art character
- `outputPath` (required): Path where the pixel art should be saved
- `pixelDimensions` (required): Target pixel dimensions ('8x8', '16x16', '32x32', '48x48', '64x64', '96x96')
- `spriteSheet` (optional): Generate sprite sheet with animations
- `model` (optional): Model to use (default: falai)
- `colors` (optional): Color palette size (4-256 colors)
- `transparentBackground` (optional): Generate pixel art with transparent background for game sprites
- `backgroundColor` (optional): Background color to make transparent ('white', 'black', 'auto', default: white)
- `generate_texture`: Generate seamless textures for 3D environments and materials
- Parameters:
- `textureDescription` (required): Description of the texture (e.g., grass field, brick wall, wood planks, sprite object)
- `outputPath` (required): Path where the texture should be saved
- `textureSize` (optional): Texture resolution ('512x512', '1024x1024', '2048x2048', default: 1024x1024)
- `seamless` (optional): Generate seamless/tileable texture
- `model` (optional): Model to use (default: falai)
- `materialType` (optional): Type of texture map ('diffuse', 'normal', 'roughness', 'displacement')
- `transparentBackground` (optional): Generate texture with transparent background for sprites/decals
- `backgroundColor` (optional): Background color to make transparent ('white', 'black', 'auto', default: white)
- `transparencyTolerance` (optional): Color variation tolerance for transparency (0-255, default: 30)
- `generate_object_sheet`: Generate multi-viewpoint reference sheets for 3D modeling
- Parameters:
- `objectDescription` (required): Description of the 3D object
- `outputBasePath` (required): Base path for output files (will append _front.png, _side.png, etc.)
- `viewpoints` (optional): Viewpoints to generate ('front', 'back', 'left', 'right', 'top', 'bottom', 'perspective')
- `model` (optional): Model to use (default: gemini - uses gemini-3-pro-image-preview)
- `style` (optional): Art style (e.g., technical drawing, concept art)
#### 3D Model Generation
- `image_to_3d`: Generate 3D models from images using advanced AI models with automatic reference image generation
- Parameters:
- `outputPath` (required): Path where the generated 3D model should be saved (.glb or .gltf)
- `prompt` (optional): Description of the 3D model to generate (used for automatic reference image generation)
- `inputImagePaths` (optional): Array of paths to input images or base64 URIs. If not provided, reference images will be generated automatically
- `model` (optional): 3D generation model ('hunyuan3d', 'trellis', 'hunyuan-world', default: hunyuan3d)
- `variant` (optional): Model variant ('single', 'multi', 'single-turbo', 'multi-turbo', default: auto-selected)
- `format` (optional): Output format ('glb', 'gltf', default: glb for web/game compatibility)
- `textured_mesh` (optional): Generate textured mesh (Hunyuan3D only, 3x cost, default: true)
- `autoGenerateReferences` (optional): Automatically generate reference images from prompt if no input images provided (default: true)
- `referenceModel` (optional): Model to use for automatic reference image generation ('openai', 'gemini', 'falai', default: gemini - uses gemini-3-pro-image-preview)
- `referenceViews` (optional): Views to generate for reference images (default: ["front", "back", "top"])
- `cleanupReferences` (optional): Clean up automatically generated reference images after 3D generation (default: true)
### Available Prompts
- `asset_generation`: Generate various types of assets for game development
- Parameters:
- `asset_type` (required): Type of asset ('image', 'video', 'audio', '3d')
- `style` (optional): Art style or theme
## Configuration
You'll need to configure API keys for the various providers:
```bash
# Environment variables
export OPENAI_API_KEY="your-openai-key"
export GEMINI_API_KEY="your-gemini-key"
export FAL_AI_API_KEY="your-fal-key"
```
### Tool Filtering (Optional)
To reduce context usage, you can restrict which tools are available:
```bash
# Only expose specific tools
export ALLOWED_TOOLS="openai_generate_image,gemini_generate_image,generate_texture"
# Available tools:
# - openai_generate_image
# - gemini_generate_image
# - falai_generate_image
# - falai_edit_image
# - generate_character_sheet
# - generate_character_variation
# - generate_pixel_art_character (with transparent background support)
# - generate_texture (with transparent background support for sprites/decals)
# - generate_object_sheet
# - image_to_3d (unified 3D generation with automatic reference images)
## Transparent Background Generation
The server supports generating images with transparent backgrounds, perfect for game sprites and decals. This uses a two-step process with native JavaScript:
1. Generate the image with a solid white/black background
2. Convert the solid background to transparent alpha using native JavaScript processing
### Features
- **Native JavaScript**: No external dependencies required
- **Auto-detection**: Automatically detects white or black backgrounds
- **Adjustable tolerance**: Control how much color variation to allow
- **PNG support**: Works with PNG images for transparency
### Examples
```bash
# Generate transparent sprite texture
generate_texture \
--textureDescription "magic fireball effect" \
--outputPath "fireball_sprite.png" \
--transparentBackground true \
--backgroundColor "black" \
--materialType "diffuse"
# Generate pixel art character with transparent background
generate_pixel_art_character \
--characterDescription "knight with sword" \
--outputPath "knight_sprite.png" \
--pixelDimensions "32x32" \
--transparentBackground true \
--colors 16
# Generate 3D model with automatic reference images
image_to_3d \
--prompt "fantasy sword with ornate handle" \
--outputPath "sword_model.glb" \
--model "hunyuan3d" \
--autoGenerateReferences true
# Generate character sheet with multiple poses
generate_character_sheet \
--characterDescription "female warrior with armor" \
--outputPath "warrior_sheet.png" \
--model "gemini" \
--style "realistic fantasy" \
--includeExpressions true \
--includePoses true
```
```
## Project Structure
```
mcp-game-asset-gen/
├── src/
│ ├── index.ts # Main server file
│ └── server.test.ts # Tests
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## License
MIT