Skip to main content

Audio Studio MCP gives Claude Code, Claude Desktop, Cursor and any other MCP client a sound studio that runs on your own Mac or Windows PC. Ask for background music or a sound effect in plain language; the model generates it locally with Stable Audio 3. Then it can loop it, normalize the loudness and export it for your game engine or video editor. There is no cloud service and no API key, and generating doesn't cost anything.

A real Claude Code session: one request produces two lo-fi BGM candidates and a seamless OGG loop for Godot
A real session, shortened. Claude picked a loop length of exactly 11 bars so the beat stays in time when it repeats.

✨ Highlights


Generate
BGM, instrument loops and sound effects from one sentence, 1–4 candidates per call

Edit
Re-style a whole clip, regenerate a time range, or extend a track

Finish
Seamless loops, fades, loudness (LUFS), 48 kHz WAV / OGG / FLAC

Local
Runs on Apple Silicon (MLX) or an NVIDIA GPU (PyTorch). Nothing is uploaded
  • Reproducible: every file gets a .json sidecar with its prompt, seed and settings.
  • Prompting built in: the server teaches the client the official Stable Audio 3 prompt format, so a request like "make it sound like a creaky door" becomes a prompt the model understands.
  • Same output as upstream: on a Mac, results for the same seed are bit-for-bit identical to the official sa3 CLI. On Windows it calls the official Stable Audio 3 PyTorch API.

🎧 Hear it

All of these were generated by this server on an M1 Mac and were not edited by hand. Open the sample page →

Sample Prompt
Lo-fi cafe
music · 30 s · 85 BPM
Lo-fi hip-hop chill track with mellow electric piano, soft vinyl crackle, low-pass filtered drums…
Epic orchestral
music · 30 s
Epic cinematic orchestral trailer music with thundering taiko drums, soaring French horns…
Chiptune adventure
music · 20 s · 150 BPM
Upbeat 8-bit chiptune adventure theme with a bright square wave lead…
Glass shatter
sfx · 3 s
source: glass bottle · action: shattering on impact · material: thick green glass · space: concrete floor
Rain & thunder
sfx · 12 s
source: heavy rain and distant thunder · space: outdoor forest at night, wide stereo
Synthwave, extended
edit · 20 s → 40 s
edit_audio continue: a 20-second track extended to 40 seconds

MP3s are in docs/samples/, with prompts and seeds in samples.json.

🧭 How it works

flowchart LR
    U["You<br/>“make a cozy cafe BGM”"] --> C["Claude Code · Desktop<br/>Cursor · any MCP client"]
    C -- "MCP" --> S["audio-studio-mcp<br/>generate · edit · process"]
    S --> M["Stable Audio 3<br/>MLX on Apple Silicon<br/>PyTorch on NVIDIA GPUs"]
    M --> F["WAV / OGG / FLAC + .json<br/>ready for game & video"]

🚀 Quick start

You need uv 0.9.20 or newer and ffmpeg. There is nothing to clone: uvx downloads and runs the published package.

macOS Windows
Hardware Apple Silicon (M1 or later), 16 GB RAM recommended NVIDIA GPU with 8 GB of VRAM or more and a current driver. Tested on an RTX 3060 12 GB
Disk About 8 GB (model ~6.9 GB) About 14 GB (model ~10.4 GB, PyTorch)
uv and ffmpeg brew install uv ffmpeg winget install astral-sh.uv and winget install Gyan.FFmpeg
Model license Nothing to do Needs a free Hugging Face account: open stabilityai/stable-audio-3-medium and accept the license once

1. Set it up once, in a terminal. This checks your computer, fetches the official Stable Audio 3 runtime at a tested commit, tells you how big the model download is and asks before downloading it. Running it again is safe; finished downloads are kept.

# macOS
uvx --python 3.11 audio-studio-mcp setup
# Windows
uvx --python 3.11 --torch-backend cu126 audio-studio-mcp setup

--torch-backend cu126 makes uv install the CUDA build of PyTorch (PyPI only has the CPU build for Windows), and --python 3.11 keeps uv away from a Python that PyTorch doesn't support yet. If uvx answers unexpected argument '--torch-backend', your uv is too old: update it with winget upgrade astral-sh.uv (or uv self update). On Windows, if you aren't logged in to Hugging Face yet, setup prints the steps: accept the license on the model page, then log in in your own terminal with uvx --from huggingface_hub hf auth login and run setup again.

2. Register it with your MCP client. Use the same command without setup:

# Claude Code, macOS
claude mcp add --scope user audio-studio -- uvx --python 3.11 audio-studio-mcp
# Claude Code, Windows
claude mcp add --scope user audio-studio -- uvx --python 3.11 --torch-backend cu126 audio-studio-mcp
Claude Desktop, Codex, VS Code, Cursor and other clients

On Windows, add "--torch-backend", "cu126" after "3.11" in each example below.

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and most other clients:

{
  "mcpServers": {
    "audio-studio": {
      "command": "uvx",
      "args": ["--python", "3.11", "audio-studio-mcp"]
    }
  }
}

If the client says it can't find uvx, put its full path in command (which uvx on macOS, where uvx on Windows). Restart Claude Desktop after editing.

Codex (~/.codex/config.toml). Codex waits only 10 seconds for a server to start and 60 seconds for a tool call by default; long tracks need more:

[mcp_servers.audio-studio]
command = "uvx"
args = ["--python", "3.11", "audio-studio-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 900

VS Code (.vscode/mcp.json, or MCP: Open User Configuration):

{
  "servers": {
    "audio-studio": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.11", "audio-studio-mcp"]
    }
  }
}

Generated files go to ~/AudioStudio (set AUDIO_STUDIO_OUTPUT_DIR to change it). uvx keeps the version it installed; to update, run uv cache clean audio-studio-mcp and then setup again.

Alternative: install from source

The install scripts from earlier versions still work. They clone the repository, put the runtime in vendor/ and the audio in outputs/ inside it, and run from .venv/.

macOS (Apple Silicon)

Requirements:

  • Apple Silicon Mac (M1 or later), 16 GB RAM recommended
  • About 6 GB of disk for the model
  • git and ffmpeg (brew install ffmpeg)
git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
./install.sh

The installer sets up uv if needed, clones the official Stable Audio 3 runtime into vendor/ at a tested commit, creates .venv/, and downloads the medium model (1.4B, ~5.9 GB) from Hugging Face. It finishes by printing the exact command to register the server:

claude mcp add --scope user audio-studio -- /path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp

Windows (NVIDIA GPU)

Requirements:

  • 64-bit Windows 10 or 11 with an NVIDIA GPU (8 GB of VRAM or more) and a current driver. Tested on an RTX 3060 12 GB
  • About 14 GB of disk for the model and PyTorch
  • git (winget install Git.Git) and ffmpeg (winget install Gyan.FFmpeg)
  • A free Hugging Face account. The PyTorch weights are gated: open stabilityai/stable-audio-3-medium and accept the license once
git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

The installer does the same steps as on macOS, but installs PyTorch with CUDA and downloads the official PyTorch checkpoint of the medium model (~10.4 GB). If you aren't logged in to Hugging Face yet, it asks for an access token with read permission (create one here). When it runs without a console (for example, started by an AI agent), it never asks: it prints the steps to log in and stops, and you re-run it after logging in. It finishes by printing the command to register the server:

claude mcp add --scope user audio-studio -- "C:\path\to\audio-studio-mcp\.venv\Scripts\audio-studio-mcp.exe"

Flash Attention is not needed. Without it, the runtime falls back to PyTorch's built-in attention.

Claude Desktop, Cursor and other clients

Add this to claude_desktop_config.json, .cursor/mcp.json or your client's MCP config:

{
  "mcpServers": {
    "audio-studio": {
      "command": "/path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp"
    }
  }
}

On Windows the command is C:\\path\\to\\audio-studio-mcp\\.venv\\Scripts\\audio-studio-mcp.exe (backslashes doubled in JSON).

Installer options
macOS Windows Effect
--model all -Model all Also download the small, fast sm-music and sm-sfx models (+2.6 GB on macOS, +7 GB on Windows)
--skip-weights -SkipWeights Don't download now; the first generation downloads them
-y -Yes Install uv without asking

On macOS, downloads are anonymous; logging in with hf auth login raises Hugging Face's rate limit. On Windows, the PyTorch weights are gated: accept the license on each model page you download (medium, small-music, small-sfx) and log in.

Then just ask:

  • "Make a 60-second lo-fi BGM loop at 85 BPM for a cafe scene, give me 3 candidates."
  • "I need a heavy wooden door slamming in a stone hallway. Export it as OGG for Godot."
  • "Extend this track to 90 seconds and normalize it to −16 LUFS."

🧰 Tools

Tool What it does
generate_audio Text to BGM, instrument loop/stem or sound effect. 1–4 candidates per call, bpm, structured SFX fields
edit_audio variation (re-style the whole clip), inpaint (regenerate a time range), continue (extend). 1–4 candidates
process_audio Trim → trim silence → mono → resample / loudness → seamless loop → fades → peak normalize or ceiling → WAV / OGG / FLAC. Never modifies the input
unload_models Free the model memory right away
Parameter notes
  • audio_type: music / instrument / sfx / raw. The server adds the prefix the model was trained with (TrackType: Music, VocalType: Instrumental, …). Without the SFX prefix, sound effects often come out as music.
  • variations: 1–4 candidates with seeds seed, seed+1, …. Use seed: -1 or leave it out for a random seed.
  • sound_source / sound_action / sound_material / sound_space: describe a sound effect by what makes it, how it evolves, its texture and the space it is in.
  • peak_ceiling_db (default −1): a safety ceiling. Louder peaks are turned down and quieter audio is never boosted. Use process_audio to normalize.
  • process_audio normalization: peak is common for SFX. loudness normalizes to a target LUFS: −14 for streaming/video, −16 for game BGM, −23 for broadcast.

Generated files are 44.1 kHz 24-bit stereo WAV, written to outputs/ in this folder. Each one has a <name>.json next to it. Processed files keep the original generation info under source.

🌐 Web UI

Prefer clicking to chatting? The same server comes with a local web page. Generate BGM and sound effects, compare the candidates, edit them (make a variation, replace a part, extend), export them for your game or video, and browse everything you've made in the library.

Web UI, Generate page: two versions of a lo-fi track to compare, and a footstep sound effect

Web UI, Edit page: a selected part of the waveform will be replaced, with the original and two new versions to compare

uvx --python 3.11 audio-studio-mcp --web 8765

Your browser opens http://127.0.0.1:8765/. Add --no-browser to start without opening it, or --preload to load the model at startup. Press Ctrl+C to stop it. On Windows, add --torch-backend cu126 after 3.11. From a source install: .venv/bin/audio-studio-mcp --web 8765 (Windows: .venv\Scripts\audio-studio-mcp.exe --web 8765).

The page and your MCP clients can share one process and one loaded model: the same port also serves MCP at /mcp. Register it once and use both at the same time. Requests from the page and from agents wait in one queue.

claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
  • Files are written to the output folder (~/AudioStudio, outputs/ in a source install, or AUDIO_STUDIO_OUTPUT_DIR). The library shows that folder, and the editor works on the files in it.
  • The page is in English, Japanese and Chinese and follows your browser's language. You can change it in the settings.

⚙️ Configuration

Environment variables
Variable Default Meaning
AUDIO_STUDIO_OUTPUT_DIR ~/AudioStudio (source install: <repo>/outputs) Where audio files are written
AUDIO_STUDIO_IDLE_UNLOAD_MIN 10 Free the models after this many idle minutes (0 = never)
AUDIO_STUDIO_SA3_MODEL medium medium (best quality, up to 380 s), sm-music or sm-sfx (small and fast, up to 120 s)
AUDIO_STUDIO_MLX_CACHE_GB 1 macOS: cap on MLX's buffer cache. Without it, a long generation can leave ~6 GB cached
AUDIO_STUDIO_DEVICE cuda if available Windows/Linux: PyTorch device, e.g. cuda, cuda:1 or cpu
AUDIO_STUDIO_SA3_DIR downloaded by setup (source install: <repo>/vendor/stable-audio-3) Use another stable-audio-3 checkout
AUDIO_STUDIO_HOME macOS ~/Library/Application Support/audio-studio-mcp, Windows %LOCALAPPDATA%\\audio-studio-mcp Where setup keeps the Stable Audio 3 runtime (~1 MB). The weights stay in the Hugging Face cache
AUDIO_STUDIO_BACKEND auto auto, sa3-mlx (Apple Silicon) or sa3-torch (PyTorch, NVIDIA)
AUDIO_STUDIO_FFMPEG ffmpeg on PATH Path to ffmpeg

Pass them with claude mcp add ... -e NAME=value or in the env block of your client config.

Share one server between sessions

Each client session normally starts its own server process. Models load on the first call and are freed after the idle timeout. To keep one warm process for every session, run it as a local HTTP server. It only listens on 127.0.0.1.

uvx --python 3.11 audio-studio-mcp --http 8765 --preload
claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp

On Windows, add --torch-backend cu126 after 3.11. From a source install, start .venv/bin/audio-studio-mcp (Windows: .venv\Scripts\audio-studio-mcp.exe) with the same options.

--web 8765 does the same and adds the web UI on the same port.

⚡ Performance

Medium model on an M1 Mac with 16 GB:

Task Time
Two 3 s sound effects, cold start ~13 s
20 s of music, warm ~10 s (2× real time)
Continue to 35 s, incl. loading the encoder ~27 s
15 s of music with sm-music, warm ~1 s

Medium model on Windows with an RTX 3060 12 GB:

Task Time
Two 3 s sound effects, cold start (incl. ~20 s model load) ~25 s
20 s of music, warm ~1.3 s
Continue to 30 s, warm ~2.2 s
380 s of music (the maximum), warm ~15 s
15 s of music with sm-music, warm ~0.7 s

On a Mac, loaded models use about 5–7 GB of memory. On the RTX 3060, the medium model peaked at about 5.3 GB of VRAM. Models are freed after the idle timeout or by unload_models.

📝 Prompting tips

From the official Stable Audio 3 prompt guide
  1. English, 1–2 sentences, up to ~45 words. Avoid vocal words such as vocals, singer or lyrics.
  2. Music: genre + adjectives → lead instruments → supporting layers → drums/rhythm → mood. Put the tempo in bpm.

    Lo-fi hip-hop chill track with mellow electric piano, soft vinyl crackle, low-pass filtered drums and soft plucked bass for a relaxed, dreamy vibe.

  3. Sound effects: fill in source, action, material and space.

    source: glass bottle / action: shattering on impact, fragments scattering / material: thick green glass, sharp bright transient / space: concrete floor, close-up, dry

  4. Match the length to the content: impacts 1–3 s, actions 3–6 s, ambience 6–15 s+, loops 6–20 s, full tracks 120–300 s (max 380 s).
  5. Timing instructions like "climax at 15 s" are not followed reliably. Generate first, then use inpaint or continue.
  6. The defaults steps=8 and cfg=1.0 are the official settings. For stricter prompt adherence, or to use negative_prompt, try cfg 3–7 (about 2× slower).
  7. Results vary a lot by seed. Ask for 2–4 variations and pick the best.

The full guide is also sent to the client as the server's instructions.

❓ FAQ

Does it run on Windows, Linux or Intel Macs?

Windows: yes, with an NVIDIA GPU. See Quick start.

Linux: with an NVIDIA GPU it uses the same PyTorch backend and should work, but it is untested. Use the cuda extra: uvx --python 3.11 --torch-backend cu126 --from "audio-studio-mcp[cuda]" audio-studio-mcp setup, and log in to Hugging Face as on Windows.

Intel Macs and AMD GPUs are not supported.

"Intel Macs are not supported" on an Apple Silicon Mac?

The environment was built with an x86_64 Python (for example an old Intel Homebrew under /usr/local) that runs under Rosetta, so MLX was skipped. With uvx, ask for uv's own arm64 Python, in setup and in your client's config: uvx --python cpython-3.11-macos-aarch64 audio-studio-mcp. With the install script, re-run ./install.sh: it asks uv for an arm64 Python and recreates such a .venv. If you set UV_PYTHON yourself, point it at an arm64 build: UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh.

Can it make songs with vocals?

No. Stable Audio 3 generates instrumental music and sound effects. It cannot produce intelligible singing or lyrics.

Can I use the generated audio commercially?

The code here is MIT. The model weights are under the Stability AI Community License, which sets the terms for the model and what it generates. Read it before commercial use. At the time of writing it allows commercial use for individuals and organizations with less than US$1M in total annual revenue.

Will an 8 GB Mac work?

It hasn't been tested. The medium model needs about 5–7 GB while loaded, so 16 GB is recommended. The small sm-music / sm-sfx models are lighter.

My loop clicks at the seam.

Use WAV or OGG for loops. MP3 adds padding at the start and end, so it can't loop seamlessly. Also try a longer loop_crossfade_ms, or ask the model to cut on a bar line.

🗺️ Roadmap

  • Apple Silicon backend (Stable Audio 3, MLX)
  • Windows backend for NVIDIA GPUs (Stable Audio 3, PyTorch)
  • Local web UI (--web)
  • One-command install with uvx
  • LoRA support (the upstream runtime already has it)

Issues and pull requests are welcome.

⭐ Like it? Star it

If Audio Studio made a sound you ended up using, please click ⭐ Star at the top of the repository page. It's free, takes one second, and helps more than it looks:

  • More people find it. Stars make the project easier to discover on GitHub, so more game developers and video makers get to use it.
  • It keeps updates coming. Every star tells me someone finds this useful. That's what keeps me working on the next update, like LoRA support.

Other ways to help: open an issue for a bug or an idea, or share a sound you made on X and tag @KanaWorks_AI.

🛠️ Development

uv run pytest                              # offline tests, no model needed
.venv/bin/python scripts/smoke_test.py     # end-to-end with the real model (~30 s on an M1)
uv build && .venv/bin/python scripts/smoke_test.py --server "uvx --python 3.11 --from $(ls dist/*.whl) audio-studio-mcp"
                                           # the same against the built wheel, as uvx runs it

On Windows: .venv\Scripts\python scripts\smoke_test.py (~45 s on an RTX 3060, including model loading).

src/audio_studio_mcp/
  server.py            MCP tools (backend-independent)
  runtime.py           where the runtime and outputs live; fetches the runtime for uvx installs
  firstrun.py          `audio-studio-mcp setup`
  weights.py           model weights: what is downloaded, downloading
  prompts.py           prompt building and the instructions sent to clients
  post.py              post-processing and export
  backends/base.py     backend interface
  backends/sa3_mlx.py  Stable Audio 3 on Apple Silicon (MLX)
  backends/sa3_torch.py  Stable Audio 3 on NVIDIA GPUs (PyTorch)
  web.py               web UI server (--web) and its JSON API
  static/              web UI (HTML/JS/CSS, no build step)

A new platform is added as another backend in backends/.

📄 License and credits

  • This project: MIT.
  • Stable Audio 3 runtime: downloaded by setup (or into vendor/ by the install scripts) at a pinned commit. It is © Stability AI and MIT-licensed.
  • Model weights: licensed under the Stability AI Community License. They are downloaded from Hugging Face (macOS: stable-audio-3-optimized; Windows: stable-audio-3-medium and the small models), not distributed here.
  • Brand: the KanaWorks_AI name, logo and the Kana character are © 東京AI映像合同会社 (Tokyo AI Visuals LLC) and are not covered by the MIT license. See docs/brand.
  • Fonts: the web UI ships IBM Plex Sans, © IBM Corp., under the SIL Open Font License 1.1 (OFL.txt). The Kana images in the web UI (static/brand) are covered by the Brand note above.
  • Built on: Stable Audio 3, MLX, PyTorch and the Model Context Protocol.

This is an independent project. It is not affiliated with or endorsed by Stability AI, Apple, NVIDIA or Anthropic.


Kana, the KanaWorks_AI mascot, waving

Made with ♥ by KanaWorks_AI

If Audio Studio saves you time, a ⭐ keeps the updates coming and helps others find it. More projects: github.com/kanaworksai-hue

Metadata

Release files for audio-studio-mcp 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for audio-studio-mcp 1.1.0
File Size Uploaded Provenance Actions
audio_studio_mcp-1.1.0.tar.gz 447.9 kB With provenance Details for audio_studio_mcp-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for audio-studio-mcp 1.1.0
File Interpreter ABI Platform Actions
audio_studio_mcp-1.1.0-py3-none-any.whl Python 3 none any Details for audio_studio_mcp-1.1.0-py3-none-any.whl

Total release size: 673.8 kB

Release files / audio_studio_mcp-1.1.0.tar.gz

Download URL audio_studio_mcp-1.1.0.tar.gz
Size 447.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5082aa0aced5bd6806b078c6a6be4520d34e0c7c23189b0855921a9245b2a00e
BLAKE2b-256 checksum
How to use checksums
701d467eaa8906b3241541315ca139cd83609a43441b976435648596fa48d6c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / audio_studio_mcp-1.1.0-py3-none-any.whl

Download URL audio_studio_mcp-1.1.0-py3-none-any.whl
Size 225.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3da1638f006e0bf59f56d76d229d07204262b8b191d69a9ab82c978a365683cc
BLAKE2b-256 checksum
How to use checksums
2e25932d192eca912ab993a83903ef0717763cc61166c66d72b8e7a8514397d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for audio-studio-mcp 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for audio_studio_mcp-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page