MCP HubMCP Hub
MubarakHAlketbi

game-asset-mcp

by: MubarakHAlketbi

An MCP server for creating 2D/3D game assets from text using Hugging Face AI models.

44created 17/03/2025
Visit
AI
GameDev

đź“ŚOverview

Purpose: The Game Asset Generator aims to simplify and accelerate the creation of 2D and 3D game assets using AI technology.

Overview: This innovative tool leverages AI to transform text prompts into game-ready assets. It supports generating both 2D assets, like pixel art sprites, and 3D models in various formats. Integrating models from Hugging Face Spaces and utilizing the Model Context Protocol (MCP) allows for efficient interaction and processing, making it suitable for game developers and AI enthusiasts alike.

Key Features:

  • 2D Asset Generation: Creates 2D game assets from text prompts, enhancing creative freedom and speed in asset creation.

  • 3D Asset Generation: Generates 3D models (OBJ and GLB formats) directly from text descriptions, streamlining the workflow from concept to implementation.

  • Multiple 3D Model Spaces: Offers integration with various 3D generation models, providing flexibility in conversion processes tailored to specific requirements.

  • MCP Integration: Enables seamless interaction with AI clients using the Model Context Protocol, enhancing usability and accessibility.

  • Robust Input Validation: Utilizes Zod for secure and reliable data processing, ensuring a smooth user experience.

Game Asset Generator using MCP and Hugging Face Spaces

This project simplifies game asset creation by leveraging AI-powered generation. It enables creation of 2D and 3D game assets from text prompts effortlessly. It integrates AI models from Hugging Face Spaces—powered by "gokaygokay/Flux-2D-Game-Assets-LoRA", "gokaygokay/Flux-Game-Assets-LoRA-v2", and one of three 3D model generation spaces (InstantMesh, Hunyuan3D-2, or Hunyuan3D-2mini-Turbo, which you must duplicate to your account)—and uses the Model Context Protocol (MCP) for seamless interaction with AI assistants like Claude Desktop.

Table of Contents

  1. Project Overview
  2. Features
  3. How It Works
  4. Prerequisites
  5. Installation
  6. Usage
  7. Configuration
  8. File Management
  9. MCP Integration
  10. Troubleshooting
  11. Advanced
  12. Contributing
  13. License

Project Overview

The Game Asset Generator (version 0.3.0) harnesses AI to streamline the creation of game assets. It supports generating 2D assets (e.g., pixel art sprites) and 3D assets (e.g., OBJ and GLB models) from text prompts, integrating with Hugging Face Spaces and the Model Context Protocol (MCP). This release introduces support for multiple 3D model generation spaces—InstantMesh, Hunyuan3D-2, and Hunyuan3D-2mini-Turbo—offering flexibility and enhanced performance. Built with Node.js and the MCP TypeScript SDK (v1.7.0), it provides a robust, cross-platform solution for asset generation.

Features

  • 2D Asset Generation: Create pixel art, sprites, or other 2D assets from text prompts (e.g., "pixel art sword").
  • 3D Asset Generation: Generate 3D models (OBJ and GLB formats) from text descriptions, with automatic image-to-model conversion.
  • Multiple 3D Model Spaces: Supports InstantMesh, Hunyuan3D-2, and Hunyuan3D-2mini-Turbo for varied 3D generation workflows.
  • MCP Integration: Interact with the tool via MCP-compatible clients like Claude Desktop.
  • File Management: Automatically saves and organizes assets in a local assets directory with resource URIs (asset://{type}/{id}).
  • Robust Input Validation: Uses Zod for secure and reliable input processing.
  • Multi-Client Support: Handles multiple simultaneous connections via SSE transport.
  • Secure Remote Access: Optional HTTPS support for safe remote communication.
  • Extensible Backend: Modular design for easy integration of new models or features.
  • Cross-Platform: Compatible with Windows, macOS, and Linux using Node.js.
  • Configurable 3D Generation: Customize parameters like inference steps, guidance scale, and turbo mode via environment variables.

How It Works

The Game Asset Generator transforms text prompts into game-ready assets through an automated pipeline:

  1. User Input: Submit a text prompt (e.g., "pixel art sword" or "isometric 3D castle").
  2. MCP Server: Routes the prompt to the appropriate tool (generate_2d_asset or generate_3d_asset).
  3. AI Model Interaction:
    • 2D Assets: Uses the Hugging Face Inference API with "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 steps).
    • 3D Assets:
      • Generates an initial image using "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 steps).
      • Converts the image to a 3D model with one of:
        • InstantMesh: Multi-step process (/preprocess, /generate_mvs, /make3d).
        • Hunyuan3D-2: Single-step process (/generation_all).
        • Hunyuan3D-2mini-Turbo: Single-step process (/generation_all) with configurable turbo modes.
  4. File Output: Saves assets (PNG for 2D, OBJ/GLB for 3D) in the assets directory.
  5. Response: Returns resource URIs (asset://3d_model/filename.glb) for immediate use.

Prompts are automatically enhanced with "high detailed, complete object, not cut off, white solid background" for optimal quality.

Prerequisites

  • Node.js: Version 16+ (includes npm).
  • Git: For cloning the repository.
  • Internet Access: Required for Hugging Face API connectivity.
  • Hugging Face Account: Needed for API access; obtain your token from https://huggingface.co/settings/tokens.
  • NPM Packages:
    • @gradio/client
    • @huggingface/inference
    • @modelcontextprotocol/sdk
    • dotenv
    • express
    • zod
    • sharp
  • Optional: Claude Desktop (or another MCP client) for enhanced interaction.

Installation

  1. Clone the Repository:

    git clone https://github.com/yourusername/game-asset-mcp.git
cd game-asset-mcp

  2. Install Dependencies:

    npm install

  3. Configure Environment:

    • Copy the example .env file: 
      cp .env.example .env
    • Edit .env with your Hugging Face API token and duplicated MODEL_SPACE.

  4. Run the Server:

    • Local (stdio transport): 
      npm start
    • Custom Working Directory: 
      node src/index.js /path/to/directory
    • Remote (SSE transport): 
      node src/index.js --sse
    • Remote with HTTPS: 
      node src/index.js --sse --https
      Requires ssl/key.pem and ssl/cert.pem.

Note: Uses ES modules ("type": "module" in package.json). Ensure Node.js 16+ is installed (node --version).

Usage

Interact with the server via an MCP client (e.g., Claude Desktop) or programmatically:

  • Generate a 2D Asset:

    • Command: generate_2d_asset prompt:"pixel art sword"
    • Output: Saves a PNG file and returns its URI.

  • Generate a 3D Asset:

    • Command: generate_3d_asset prompt:"isometric 3D castle"
    • Output: Saves OBJ/GLB files and intermediate images, returning their URIs. Provides an operation ID for long-running tasks.

Prompt Examples

  • Natural Interaction:
    • generate_2d_sprite prompt:"pixel art sword"
    • generate_3d_model prompt:"isometric 3D castle"

With Claude Desktop, type commands directly in the interface after configuration.

Configuration

Customize the server via the .env file:

Required Settings

  • HF_TOKEN: Hugging Face API token. 
    HF_TOKEN=your_hf_token
  • MODEL_SPACE: Your duplicated 3D model space (e.g., your-username/InstantMesh).

Optional 3D Model Settings

VariableDescriptionValid Range / Default
MODEL_3D_STEPSInference stepsVaries by space
MODEL_3D_GUIDANCE_SCALEHow closely the model follows the prompt0.0-100.0 (default: 5.0-5.5)
MODEL_3D_OCTREE_RESOLUTIONDetail level of the 3D modelVaries by space
MODEL_3D_SEEDRandomness control0-10,000,000 (default: varies)
MODEL_3D_REMOVE_BACKGROUNDRemove image backgroundtrue/false (default: true)
MODEL_3D_TURBO_MODEGeneration mode (Hunyuan3D-2mini-Turbo only)Turbo, Fast, Standard (default: Turbo)
MODEL_SPACE_TYPEOverride space type detectioninstantmesh, hunyuan3d, hunyuan3d_mini_turbo

Space-Specific Defaults

  • InstantMesh:
    • Steps: 30-75 (default: 75)
    • Seed: 42
  • Hunyuan3D-2:
    • Steps: 20-50 (default: 20)
    • Guidance Scale: 5.5
    • Octree Resolution: 256, 384, 512 (default: 256)
    • Seed: 1234
  • Hunyuan3D-2mini-Turbo:
    • Steps: 1-100 (default: 5 for Turbo, 10 for Fast, 20 for Standard)
    • Guidance Scale: 5.0
    • Octree Resolution: 16-512 (default: 256)
    • Seed: 1234

Transport Settings

  • PORT: SSE transport port (default: 3000). 
    PORT=3000

Claude Desktop Setup

Edit the config file:

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "game-asset-generator": {
      "command": "node",
      "args": ["/full/path/to/game-asset-mcp/src/index.js"]
    }
  }
}

Restart Claude Desktop after editing.

File Management

  • Storage Location: Assets are saved in ./assets within the working directory.
  • Naming Convention: Files use a prefix, tool name, timestamp, and unique ID (e.g., 2d_asset_generate_2d_asset_1698765432_abcd1234.png).
  • Customization: Set a custom directory: 
    node src/index.js /path/to/custom/directory
  • Resource Access: Use MCP URIs (e.g., asset://2d_asset/filename.png) to list or read assets.

MCP Integration

The Model Context Protocol (MCP) enables this tool to serve AI clients securely:

  • Tools: generate_2d_asset, generate_3d_asset.
  • Resources: Managed via asset:// URIs.
  • Prompts: generate_2d_sprite, generate_3d_model.
  • Compatibility: Works with Claude Desktop and other MCP clients.

Troubleshooting

  • API Errors: Check network connectivity or rate limits; review ./logs/server.log.
  • Authentication Issues: Verify HF_TOKEN and MODEL_SPACE in .env.
  • ES Modules Error: Ensure Node.js 16+ (node --version).
  • Logs: Inspect detailed logs: 
    tail -f ./logs/server.log

Advanced

API Endpoints and Integration

  • 2D Asset Generation: Uses "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 steps).
  • 3D Asset Image Generation: Uses "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 steps).
  • 3D Model Conversion:
    • InstantMesh: Multi-step (/check_input_image, /preprocess, /generate_mvs, /make3d).
    • Hunyuan3D-2: Single-step (/generation_all).
    • Hunyuan3D-2mini-Turbo: Single-step (/generation_all) with turbo modes.

Versioning

  • Current Version: 0.3.0 (Added Hunyuan3D-2mini-Turbo support).
  • MCP SDK Version: 1.7.0.
  • Format: MAJOR.MINOR.PATCH (SemVer).

Backend Architecture

  • Core File: src/index.js.
  • Dependencies: See package.json.
  • Security: Zod validation, path traversal prevention, HTTPS support, rate limiting.
  • Performance: Async processing, retry with backoff, GPU quota handling.

Contributing

We welcome contributions! To participate:

  1. Fork the repository.
  2. Make changes (features, bug fixes, docs).
  3. Submit a pull request detailing your changes.
  4. Open issues to report bugs or suggest improvements.

Follow standard coding conventions and include tests where applicable.

License

Licensed under the MIT License. See the LICENSE file for details.