HF Assets

An MCP server that generates game assets through free Hugging Face Spaces — no GPU and no subscription: images, 3D meshes, sound and music. A free Hugging Face token is optional and raises the daily quota. Plus procedural synthesizers that spend no quota at all.

The ZeroGPU quota is shared by all Spaces and resets 24 hours after first use, so the cheap option goes first and the expensive one is only run for the final take.

Install

npm install
npm run build

Node 20 or newer. The only runtime dependencies are the official MCP SDK, the official Gradio JavaScript client and Zod.

Related MCP server: grok-game-mcp

Run it as an MCP server

node dist/server.js

Register it with a client. Claude Code, for example:

claude mcp add hf-assets -- node /path/to/hf-assets/dist/server.js

or, for a client that reads a config file:

{
  "mcpServers": {
    "hf-assets": {
      "command": "node",
      "args": ["/path/to/hf-assets/dist/server.js"],
      "env": { "HF_TOKEN": "hf_...", "HF_ASSETS_ROOT": "/path/to/hf-assets" }
    }
  }
}

This repository ships a .mcp.json that points at the server next to it, so a client that reads it needs no configuration at all.

The tools

render_mesh takes a couple of minutes on CPU: the client needs a longer timeout than the default for that call. Lower samples, width and height for a quick look.

The resources

How it is put together

src/
  server.ts        the MCP server: every tool and resource
  catalogue.ts     the models: Space, licence, cost (the one source of truth)
  paths.ts         the working root and the package root
  types.ts         what the tools hand back
  gradio.ts        the Hugging Face Space layer, and the take/sidecar writer
  image.ts         text -> image
  mesh.ts          image -> mesh
  audio.ts         text -> sound, music, speech
  audio-batch.ts   a manifest of audio assets
  model-sheet.ts   the model sheet prompt builder
  render.ts        the Blender subprocess
  dsp/
    fft.ts         a complex FFT for any length
    engine.ts      the engine loop
    sfx.ts         vehicle Foley
    music.ts       the breakbeat suite
    postprocess.ts trimming, looping, normalising
    arrays.ts      the numpy-shaped array helpers
    rng.ts         a seeded random generator
    wav.ts         WAV natively, the rest through ffmpeg
blender/
  render_raw.py    the Blender mesh renderer
  studio_render.py the lights, the backdrop and the camera

blender/ is the one part that is still Python: Blender's API is Python, so the studio renderer is a script the server runs as a subprocess.

Why not the official Hugging Face MCP server?

Hugging Face ships an official MCP server that can search the Hub and call any Space that exposes itself as an MCP tool, and Gradio can turn an app into an MCP server with mcp_server=True. If all you want is to call one of those Spaces from an agent, use it: it is less to install.

This project exists for what that does not cover.

• Not every Space is an MCP tool. The author of a Space has to switch MCP on. Checked on 2026-10-20, four of the nine Spaces used here expose it (Z-Image Turbo, Qwen-Image, TRELLIS, Chatterbox) and five do not: FLUX.2 Klein, Hunyuan3D-2, Stable Audio Open, MMAudio and ACE-Step. Between them they cover editing from a reference, one of the two image-to-3D models and all of the sound effects and music. Here they are reached through the plain Gradio API, which every Space has. A Space may turn MCP on later, and then the official server will reach it too.

• One tool per job, not a raw API. TRELLIS alone exposes twelve tools through MCP, and the agent has to work out which to call and in what order. Here, generate_mesh is one call, with the right parameters filled in. Likewise for image sizes, which Z-Image only accepts as exact strings.

• A licence gate. list_models says which model may ship, and generate_audio_batch refuses a manifest that names a non-commercial model (MMAudio is CC-BY-NC-4.0), so a prototype take cannot be mistaken for a shippable one.

• Provenance. Every file is written next to a .json with the prompt, the parameters, the seed and the raw Space response.

• Work after the generation. postprocess_audio trims, crossfades a loop and normalises; render_mesh shows the agent the mesh from six angles in Blender so it can judge the shape; model_sheet builds a prompt that works for image-to-3D.

• Things that need no Space at all. synth_sound makes an engine loop that survives a pitch shift, Foley and music with no network and no quota.

What is the same: both spend the same ZeroGPU quota, and both depend on someone else's free Space staying up.

Why this works

A synthesised loop survives a pitch shift. A recorded or generated loop has an arbitrary length, so when the revs of an engine or a motor change in-game the seam produces a phase jump — a click on every revolution. The synthesis is built so that the loop contains a whole number of engine cycles and the seam matches in phase at any pitch. The synth_sound tool checks this and reports:

seam step 0.0123 vs sharpest in-loop step 0.0254 -> looping is clean

Selection stays human. The pipeline is split on purpose: generation is automatic, choosing the take is not. Candidates sit next to their prompt, parameters and raw Space response (*.json), a human listens, picks one, and only then does postprocess_audio turn the chosen take into a finished file.

Every run is traceable. Next to the result sits a .json with the prompt, the parameters, the seed and the Space response, so a take can be repeated. The one exception is Stable Audio Open: its Space takes no seed, so its takes are numbered but cannot be reproduced exactly.

ZeroGPU quota

• The quota is shared between images, meshes and sound.

• It resets 24 hours after first use, not at midnight.

• A Space reserves time before it starts: if there is less than the reservation left, the run is rejected immediately, even if the computation itself would have taken seconds.

Model licences

Licences change: check the model page before using a model in a commercial project. list_models carries the same table, and generate_audio_batch refuses a manifest that names a non-commercial model. Prompts and images are uploaded to Hugging Face.

Prompt templates

Templates for model sheets, concept art and prop sheets live in PROMPT_TEMPLATES.md, also served as the hf-assets://prompt-templates resource.

Development

npm run dev        # run the server from the sources
npm run build      # the server tests run dist/server.js, so build first
npm test           # the test suite
npm run typecheck  # tsc --noEmit, sources and tests

The tests cover the FFT against reference values from numpy, the engine loop against reference output of the original implementation, the post-processing chain and the server itself over a real stdio pipe.

Licence

MIT — see LICENSE. It covers the code and the prompt templates. The models behind the Spaces have their own licences, listed above.

Author: Ivan Glazyrin (glazrus97@gmail.com).