sfx-gen-mcp

An MCP server that lets LLM agents (Claude Code, etc.) generate game sound effects locally with Stability AI's Stable Audio Open. No API keys, no per-generation cost — your agent asks for "a coin pickup sound in assets/sounds/" and gets a .wav file.

Tools

• generate_sfx — text prompt → .wav file(s). Parameters: prompt, duration_seconds (0.5–47), steps, cfg_scale, seed, negative_prompt, variations (1–4 takes per call), output_dir, filename. Returns JSON with saved file paths and the seed used (so a liked sound can be reproduced or varied).

• sfx_server_status — model/device/load state.

The sfx-gen-ctl control server (stdio, see Control server) adds three more:

• sfx_ensure_server — start the daemon if it is not listening, retrying on failure. No-op when it is already up.

• sfx_status — daemon reachability, launchd supervision state, and the loaded model/device when it is running.

• sfx_troubleshoot — ok/warn/fail checklist with copy-pasteable fixes.

Related MCP server: mcp-soundfx

Requirements

• Python 3.10+

• ~10 GB disk for model weights, ~12 GB RAM while generating

• GPU strongly recommended: CUDA or Apple Silicon (MPS is supported and patched at runtime — upstream stable-audio-tools uses float64 which MPS lacks)

• Hugging Face access to the gated model: accept the license at stabilityai/stable-audio-open-1.0, then hf auth login

This server is the local-SFX half of game-audio-kit, which bundles it with a music/voice MCP server and a Claude Code audition-workflow skill — but it stands alone: any MCP client can use it directly.

Install

Not yet on PyPI — install from this repo:

uv tool install git+https://github.com/JimCline/sfx-gen-mcp
# or: pip install git+https://github.com/JimCline/sfx-gen-mcp

Run

Two modes:

Shared daemon (recommended) — one resident model serves every client; sessions connect over streamable HTTP and skip the per-session model load:

PYTORCH_ENABLE_MPS_FALLBACK=1 sfx-gen-mcp --transport http --port 8756

claude mcp add --transport http --scope user sfx-gen http://127.0.0.1:8756/mcp

Per-session (stdio) — simplest, but each client process loads its own copy of the model:

claude mcp add --scope user --env PYTORCH_ENABLE_MPS_FALLBACK=1 -- sfx-gen sfx-gen-mcp

Concurrent requests to the daemon are serialized with a lock — a second client queues instead of contending for the GPU.

The model lazy-loads on the first generate_sfx call (~20–40s), then stays resident. On an Apple M-series GPU a 50-step clip takes roughly 15–30s.

Env vars

Idle shutdown

Once the model has been loaded, the server exits after SFX_IDLE_TIMEOUT seconds (default 30 min) without a generation, releasing the ~10 GB of model memory. Run it under a supervisor that restarts it (launchd KeepAlive, systemd Restart=always, docker --restart) and it respawns instantly as a small model-free listener; the next generate_sfx call reloads the model. A server that has never loaded the model never exits.

Control server

The daemon's tools are reached over HTTP, so when it is down they are gone — a "restart yourself" tool hosted on it could never be called. sfx-gen-ctl is a second, dependency-light MCP server that solves this by running over stdio: the client spawns it per session, so it answers whether or not the daemon is alive. It never imports torch and never loads the model.

If you installed the package (so the console script is on PATH):

claude mcp add --scope user -- sfx-gen-ctl sfx-gen-ctl

Straight from a checkout, with no install — the control server needs only mcp, never torch:

claude mcp add --scope user -- sfx-gen-ctl \
  uv run --no-project --with 'mcp>=1.9,<2' python /path/to/sfx-gen-mcp/src/sfx_gen_mcp/control.py

Register it alongside the HTTP daemon and an agent that finds generate_sfx missing can call sfx_ensure_server to bring the service back, then sfx_troubleshoot if it will not start.

sfx_ensure_server prefers launchctl kickstart over spawning its own process, so it never races the KeepAlive supervisor for port 8756; it falls back to a detached spawn only when no launchd job is installed. Readiness is a TCP connect, not an HTTP status check — FastMCP answers a bare GET /mcp with 4xx, so polling for 200 would never see a healthy daemon.

Note that bringing the daemon up does not necessarily re-establish an MCP connection that already failed in an open session; run /mcp to reconnect, or start a new session.

It honours the same SFX_HOST / SFX_PORT as the daemon, plus SFX_LAUNCHD_LABEL (default com.sfx-gen-mcp) and SFX_LOG.

Pinning mcp

mcp 2.0 removed the mcp.server.fastmcp module this server imports, so the dependency is capped at mcp>=1.9,<2. If you launch the server via uv run --with ..., pin it there too — an unpinned --with mcp will silently start resolving to 2.x and the daemon will crash-loop on ModuleNotFoundError: No module named 'mcp.server.fastmcp'. In a launchd plist, remember to escape < as <.

macOS: run at login

See launchd/com.sfx-gen-mcp.plist for a LaunchAgent template: copy to ~/Library/LaunchAgents/, adjust paths, then launchctl load ~/Library/LaunchAgents/com.sfx-gen-mcp.plist. Idle memory is small — the model only loads when the first generation is requested.

Prompting tips

Concrete, physical descriptions work best:

• "sword clashing against metal shield, sharp ring" not "battle sound"

• "footsteps on gravel, slow walking pace" not "walking"

• Use negative_prompt: "music, voices" to keep ambiences clean

• Impacts: 1–2s. UI blips: ~1s. Ambient loops: 10–30s.

License

MIT for this server. Model weights are governed by the Stability AI Community License; outputs are usable in commercial projects for organizations under $1M annual revenue — review the license for your situation.