Skip to content
Back to search

game-asset-mcp

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sato942--game-asset-mcp/badge.svg)](/listings/sato942--game-asset-mcp)

HTML

<a href="/listings/sato942--game-asset-mcp"><img src="/api/listings/sato942--game-asset-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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: ```bash cp .env.example .env ``` - Edit `.env` with your **Hugging Face API token** and duplicated **MODEL_SPACE**. See [Configuration](#configuration) for details.

4. **Run the Server**: - **Local (stdio transport)**: ```bash npm start ``` - **Custom Working Directory**: ```bash node src/index.js /path/to/directory ``` - **Remote (SSE transport)**: ```bash node src/index.js --sse ``` - **Remote with HTTPS**: ```bash node src/index.js --sse --https ``` Requires `ssl/key.pem` and `ssl/cert.pem` (see [ssl/README.md](ssl/README.md)).

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 310 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Project owner will look into this repository soon, expect an update in JUNE 2026
  2. # Game Asset Generator using MCP and Hugging Face Spaces
  3. This project is an innovative tool that simplifies game asset creation by leveraging AI-powered generation. Whether you're a game developer seeking rapid prototypes or an AI enthusiast exploring generative models, this tool enables you to create **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**.
  4. <p align="center">
  5. <a href="https://pay.ziina.com/MubarakHAlketbi">
  6. <img src="https://img.shields.io/badge/Support_Me-Donate-9626ff?style=for-the-badge&logo=https%3A%2F%2Fimgur.com%2FvwC39JY" alt="Support Me - Donate">
  7. </a>
  8. <a href="https://github.com/RooVetGit/Roo-Code">
  9. <img src="https://img.shields.io/badge/Built_With-Roo_Code-412894?style=for-the-badge" alt="Built With - Roo Code">
  10. </a>
  11. <br>
  12. <a href="https://glama.ai/mcp/servers/@MubarakHAlketbi/game-asset-mcp">
  13. <img width="380" height="200" src="https://glama.ai/mcp/servers/@MubarakHAlketbi/game-asset-mcp/badge" />
  14. </a>
  15. </p>
  16. ---
  17. ## Table of Contents
  18. 1. [Project Overview](#project-overview)
  19. 2. [Features](#features)
  20. 3. [How It Works](#how-it-works)
  21. 4. [Prerequisites](#prerequisites)
  22. 5. [Installation](#installation)
  23. 6. [Usage](#usage)
  24. 7. [Configuration](#configuration)
  25. 8. [File Management](#file-management)
  26. 9. [MCP Integration](#mcp-integration)
  27. 10. [Troubleshooting](#troubleshooting)
  28. 11. [Advanced](#advanced)
  29. 12. [Contributing](#contributing)
  30. 13. [License](#license)
  31. ---
  32. ## Project Overview
  33. 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.
  34. ---
  35. ## Features
  36. - **2D Asset Generation**: Create pixel art, sprites, or other 2D assets from text prompts (e.g., "pixel art sword").
  37. - **3D Asset Generation**: Generate 3D models (OBJ and GLB formats) from text descriptions, with automatic image-to-model conversion.
  38. - **Multiple 3D Model Spaces**: Supports `InstantMesh`, `Hunyuan3D-2`, and `Hunyuan3D-2mini-Turbo` for varied 3D generation workflows.
  39. - **MCP Integration**: Seamlessly interact with the tool via MCP-compatible clients like **Claude Desktop**.
  40. - **File Management**: Automatically saves and organizes assets in a local `assets` directory with resource URIs (e.g., `asset://{type}/{id}`).
  41. - **Robust Input Validation**: Uses **Zod** for secure and reliable input processing.
  42. - **Multi-Client Support**: Handles multiple simultaneous connections via **SSE transport**.
  43. - **Secure Remote Access**: Optional **HTTPS** support for safe remote communication.
  44. - **Extensible Backend**: Modular design for easy integration of new models or features.
  45. - **Cross-Platform**: Compatible with Windows, macOS, and Linux using **Node.js**.
  46. - **Configurable 3D Generation**: Customize parameters like inference steps, guidance scale, and turbo mode via environment variables.
  47. ---
  48. ## How It Works
  49. The Game Asset Generator transforms text prompts into game-ready assets through an automated pipeline:
  50. 1. **User Input**: Submit a text prompt (e.g., "pixel art sword" or "isometric 3D castle").
  51. 2. **MCP Server**: Routes the prompt to the appropriate tool (`generate_2d_asset` or `generate_3d_asset`).
  52. 3. **AI Model Interaction**:
  53. - **2D Assets**: Utilizes the **Hugging Face Inference API** with `"gokaygokay/Flux-2D-Game-Assets-LoRA"` (50 steps).
  54. - **3D Assets**:
  55. - Generates an initial image using `"gokaygokay/Flux-Game-Assets-LoRA-v2"` (30 steps).
  56. - Converts the image to a 3D model using one of:
  57. - **InstantMesh**: Multi-step process (`/preprocess`, `/generate_mvs`, `/make3d`).
  58. - **Hunyuan3D-2**: Single-step process (`/generation_all`).
  59. - **Hunyuan3D-2mini-Turbo**: Single-step process (`/generation_all`) with configurable turbo modes.
  60. 4. **File Output**: Saves assets (PNG for 2D, OBJ/GLB for 3D) in the `assets` directory.
  61. 5. **Response**: Returns resource URIs (e.g., `asset://3d_model/filename.glb`) for immediate use.
  62. ### Workflow Diagram
  63. ```
  64. User Prompt → MCP Server → AI Model(s) → Local File → Resource URI Response
  65. ```
  66. Prompts are automatically enhanced with "high detailed, complete object, not cut off, white solid background" for optimal quality.
  67. ---
  68. ## Prerequisites
  69. - **Node.js**: Version 16+ (includes `npm`).
  70. - **Git**: For cloning the repository.
  71. - **Internet Access**: Required for Hugging Face API connectivity.
  72. - **Hugging Face Account**: Needed for API access; obtain your token from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).
  73. - **NPM Packages**:
  74. - `@gradio/client`: Interacts with Hugging Face Spaces.
  75. - `@huggingface/inference`: For direct model inference.
  76. - `@modelcontextprotocol/sdk`: Implements the MCP server.
  77. - `dotenv`: Loads environment variables.
  78. - `express`: Enables SSE transport.
  79. - `zod`: Ensures input validation.
  80. - `sharp`: Handles image processing.
  81. - **Optional**: **Claude Desktop** (or another MCP client) for enhanced interaction.
  82. ---
  83. ## Installation
  84. 1. **Clone the Repository**:
  85. ```bash
  86. git clone https://github.com/yourusername/game-asset-mcp.git
  87. cd game-asset-mcp
  88. ```
  89. 2. **Install Dependencies**:
  90. ```bash
  91. npm install
  92. ```
  93. 3. **Configure Environment**:
  94. - Copy the example `.env` file:
  95. ```bash
  96. cp .env.example .env
  97. ```
  98. - Edit `.env` with your **Hugging Face API token** and duplicated **MODEL_SPACE**. See [Configuration](#configuration) for details.
  99. 4. **Run the Server**:
  100. - **Local (stdio transport)**:
  101. ```bash
  102. npm start
  103. ```
  104. - **Custom Working Directory**:
  105. ```bash
  106. node src/index.js /path/to/directory
  107. ```
  108. - **Remote (SSE transport)**:
  109. ```bash
  110. node src/index.js --sse
  111. ```
  112. - **Remote with HTTPS**:
  113. ```bash
  114. node src/index.js --sse --https
  115. ```
  116. Requires `ssl/key.pem` and `ssl/cert.pem` (see [ssl/README.md](ssl/README.md)).
  117. > **Note**: Uses ES modules (`"type": "module"` in `package.json`). Ensure Node.js 16+ is installed (`node --version`).
  118. ---
  119. ## Usage
  120. Interact with the server via an **MCP client** (e.g., Claude Desktop) or programmatically:
  121. - **Generate a 2D Asset**:
  122. - **Command**: `generate_2d_asset prompt:"pixel art sword"`
  123. - **Output**: Saves a PNG file (e.g., `2d_asset_generate_2d_asset_1698765432.png`) and returns its URI.
  124. - **Generate a 3D Asset**:
  125. - **Command**: `generate_3d_asset prompt:"isometric 3D castle"`
  126. - **Output**: Saves OBJ/GLB files and intermediate images, returning their URIs. Provides an operation ID for long-running tasks.
  127. ### Prompt Examples
  128. - **Natural Interaction**:
  129. - `generate_2d_sprite prompt:"pixel art sword"`
  130. - `generate_3d_model prompt:"isometric 3D castle"`
  131. ### With Claude Desktop
  132. After configuring (see [Configuration](#configuration)), type commands directly in the interface.
  133. ---
  134. ## Configuration
  135. Customize the server via the `.env` file:
  136. ### Required Settings
  137. - **HF_TOKEN**: Hugging Face API token.
  138. ```plaintext
  139. HF_TOKEN=your_hf_token
  140. ```
  141. - **MODEL_SPACE**: Your duplicated 3D model space (e.g., `your-username/InstantMesh`).
  142. - Duplicate one of:
  143. - [InstantMesh](https://huggingface.co/spaces/tencentARC/InstantMesh)
  144. - [Hunyuan3D-2](https://huggingface.co/spaces/tencent/Hunyuan3D-2)
  145. - [Hunyuan3D-2mini-Turbo](https://huggingface.co/spaces/tencent/Hunyuan3D-2mini-Turbo)
  146. ```plaintext
  147. MODEL_SPACE=your-username/InstantMesh
  148. ```
  149. ### Optional 3D Model Settings
  150. | Variable | Description | Valid Range/Default |
  151. |---------------------------|-----------------------------------------------|---------------------------|
  152. | `MODEL_3D_STEPS` | Inference steps | Varies by space (see below) |
  153. | `MODEL_3D_GUIDANCE_SCALE`| How closely the model follows the prompt | 0.0-100.0 (default: 5.0-5.5) |
  154. | `MODEL_3D_OCTREE_RESOLUTION` | Detail level of the 3D model | Varies by space (see below) |
  155. | `MODEL_3D_SEED` | Randomness control | 0-10000000 (default: varies) |
  156. | `MODEL_3D_REMOVE_BACKGROUND` | Remove image background | `true`/`false` (default: `true`) |
  157. | `MODEL_3D_TURBO_MODE` | Generation mode (Hunyuan3D-2mini-Turbo only) | `Turbo`, `Fast`, `Standard` (default: `Turbo`) |
  158. | `MODEL_SPACE_TYPE` | Override space type detection | `instantmesh`, `hunyuan3d`, `hunyuan3d_mini_turbo` |
  159. #### Space-Specific Defaults
  160. - **InstantMesh**:
  161. - Steps: 30-75 (default: 75)
  162. - Seed: Default 42
  163. - **Hunyuan3D-2**:
  164. - Steps: 20-50 (default: 20)
  165. - Guidance Scale: Default 5.5
  166. - Octree Resolution: `256`, `384`, `512` (default: `256`)
  167. - Seed: Default 1234
  168. - **Hunyuan3D-2mini-Turbo**:
  169. - Steps: 1-100 (default: 5 for `Turbo`, 10 for `Fast`, 20 for `Standard`)
  170. - Guidance Scale: Default 5.0
  171. - Octree Resolution: 16-512 (default: 256)
  172. - Seed: Default 1234
  173. ### Transport Settings
  174. - **PORT**: SSE transport port (default: 3000).
  175. ```plaintext
  176. PORT=3000
  177. ```
  178. ### Claude Desktop Setup
  179. Edit the config file:
  180. - **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  181. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  182. ```json
  183. {
  184. "mcpServers": {
  185. "game-asset-generator": {
  186. "command": "node",
  187. "args": ["/full/path/to/game-asset-mcp/src/index.js"]
  188. }
  189. }
  190. }
  191. ```
  192. Restart Claude Desktop after editing.
  193. ---
  194. ## File Management
  195. - **Storage Location**: Assets are saved in `./assets` within the working directory.
  196. - **Naming Convention**: Files use a prefix, tool name, timestamp, and unique ID (e.g., `2d_asset_generate_2d_asset_1698765432_abcd1234.png`).
  197. - **Customization**: Set a custom directory:
  198. ```bash
  199. node src/index.js /path/to/custom/directory
  200. ```
  201. - **Resource Access**: Use MCP URIs (e.g., `asset://2d_asset/filename.png`) to list or read assets.
  202. ---
  203. ## MCP Integration
  204. The **Model Context Protocol (MCP)** enables this tool to serve AI clients securely:
  205. - **Tools**: `generate_2d_asset`, `generate_3d_asset`.
  206. - **Resources**: Managed via `asset://` URIs.
  207. - **Prompts**: `generate_2d_sprite`, `generate_3d_model`.
  208. - **Compatibility**: Works with **Claude Desktop** and other MCP clients.
  209. ---
  210. ## Troubleshooting
  211. - **API Errors**: Check network connectivity or rate limits; review `./logs/server.log`.
  212. - **Authentication Issues**: Verify `HF_TOKEN` and `MODEL_SPACE` in `.env`.
  213. - **ES Modules Error**: Ensure Node.js 16+ (`node --version`).
  214. - **Logs**: Inspect detailed logs:
  215. ```bash
  216. tail -f ./logs/server.log
  217. ```
  218. ---
  219. ## Advanced
  220. ### API Endpoints and Integration
  221. - **2D Asset Generation**: Uses `"gokaygokay/Flux-2D-Game-Assets-LoRA"` (50 steps).
  222. - **3D Asset Image Generation**: Uses `"gokaygokay/Flux-Game-Assets-LoRA-v2"` (30 steps).
  223. - **3D Model Conversion**:
  224. - **InstantMesh**: Multi-step (`/check_input_image`, `/preprocess`, `/generate_mvs`, `/make3d`).
  225. - **Hunyuan3D-2**: Single-step (`/generation_all`).
  226. - **Hunyuan3D-2mini-Turbo**: Single-step (`/generation_all`) with turbo modes.
  227. ### Versioning
  228. - **Current Version**: 0.3.0 (Added Hunyuan3D-2mini-Turbo support).
  229. - **MCP SDK Version**: 1.7.0.
  230. - **Format**: MAJOR.MINOR.PATCH (SemVer).
  231. ### Backend Architecture
  232. - **Core File**: `src/index.js`.
  233. - **Dependencies**: See `package.json`.
  234. - **Security**: Zod validation, path traversal prevention, HTTPS support, rate limiting.
  235. - **Performance**: Async processing, retry with backoff, GPU quota handling.
  236. ---
  237. ## Contributing
  238. We welcome contributions! To participate:
  239. 1. **Fork the Repository**: Create your copy on GitHub.
  240. 2. **Make Changes**: Add features, fix bugs, or enhance docs.
  241. 3. **Submit a Pull Request**: Detail your changes.
  242. 4. **Open Issues**: Report bugs or suggest improvements.
  243. Follow standard coding conventions and include tests where applicable.
  244. ---
  245. ## License
  246. Licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.