Soundbox

MCP Server

A local sound studio your agent can call

Soundbox runs an MCP server inside its own process, so the agent writing your code can also generate the sound effects, music and speech that go with it. Generation runs on your GPU from open-weight models, and the tools return absolute paths to WAVs on your disk. No cloud service is involved, so there is no key, no account and no per-generation bill.

Claude CodeClaude DesktopCursorAny MCP client
Connect it in one lineRead the tool reference

Connect it in one line

The MCP server runs inside the main Soundbox process. There is no separate daemon to start: if the app is running, the server is up.

  1. 1

    Start Soundbox

    Install and run it. The full walkthrough, including downloading model weights, is in the install guide. The server listens on 127.0.0.1:17494.

  2. 2

    Point your client at it

    In Claude Code, that is one command:

    claude mcp add --transport http soundbox http://127.0.0.1:17494/mcp

    Clients that take a JSON config file, such as Claude Desktop and Cursor, use the same URL:

    {"mcpServers":{"soundbox":{"type":"http","url":"http://127.0.0.1:17494/mcp"}}}

    The URL has no trailing slash. Soundbox rewrites /mcp onto the mounted path internally and does not answer a POST with a redirect, so the URL works as pasted.

  3. 3

    Ask for a sound

    There is nothing else to configure. Ask in your current conversation:

    Generate a heavy wooden door slamming in a stone corridor, about 3 seconds, and put it in assets/audio/.

There is no key and no account, because there is no auth and no cloud. The agent and the server run on the same machine and talk over a loopback socket.

What comes back is a path

Every result from soundbox.generate carries an absolute filesystem path to a WAV on your disk. The agent has no base64 to decode, no signed URL that expires, and no id to exchange for bytes in a second call. Its next step is ordinary shell work:

ffmpeg -i /home/you/.soundbox/sounds/9f1c2ae4….wav assets/audio/vault-door.ogg

This works because the agent and Soundbox run on the same machine and share a filesystem.

A worked example

One turn with one tool call, producing one file, as it appears in your agent's chat.

You

The vault door in level 2 has no sound. Make one and wire it up.

AI

I'll generate it locally and drop it into your assets folder.

soundbox.generate prompt: "heavy wooden door slamming in a stone corridor", duration_s: 3

C:\Users\you\.soundbox\sounds\9f1c2ae4….wav

cp C:\Users\you\.soundbox\sounds\9f1c2ae4….wav assets/audio/vault-door.wav

Done: assets/audio/vault-door.wav, 3 seconds, referenced from the door's interact handler.

The second step is an ordinary shell copy, because the first step returned a path on the same disk. The chat wording is written for this illustration; the call and its result shape are real.

The tools your agent gets

21 of them, in 4 groups. Arguments, defaults and return shapes are in the tool reference.

Sounds

Make a sound effect and find it again. Every sound-shaped result carries an absolute path to a WAV on this machine, so the agent can use its ordinary file tools from there.

  • soundbox.generateslow

    Renders one or more sounds from a text description and saves them to the library. Blocks until the audio is on disk.

  • soundbox.enhance_prompt

    Turns a vague prompt (“scary sound”) into a concrete one, optionally several. Requires the local prompt assistant to be enabled; if it is off, the tool says so.

  • soundbox.list_models

    Available models with status and licence. Also lists each speech model's delivery options. A misspelled option is ignored silently, with no error.

  • soundbox.list_sounds

    Search what has already been made. Call it before generating; the sound may already exist.

  • soundbox.get_sound

    Fetch a single sound by id, including its absolute file path.

  • soundbox.separateslow

    Splits a sound into vocals, drums, bass and other, each saved as its own sound with its own path. You can keep some and merge the rest back into one sound: the original minus the stems you kept.

  • soundbox.delete_sounddestructive

    Permanently deletes a sound and its audio file.

Voices

Spoken words take a separate path: soundbox.generate will not say them. speak is the one-off read. Put anything you want to keep and rework in a story.

  • soundbox.list_voices

    The voices a script can be read in. Call it before writing one, so lines can be cast to real voice ids.

  • soundbox.speakslow

    Reads text aloud in a saved voice and saves it to the library. Pass one line, or several with different voices. Blocks until the audio is on disk.

Stories

A story is a script that persists. Each line has a position in time, can be re-read on its own, and persists after the conversation that made it.

  • soundbox.create_story

    Creates the empty script everything else in this group operates on.

  • soundbox.list_stories

    Existing stories, most recently worked on first.

  • soundbox.get_story

    Returns the whole script line by line: text, voice, timing, and whether each line has been voiced yet. Use it to inspect what the agent built.

  • soundbox.add_lines

    Appends spoken lines, pauses, or existing library sounds to the script. Add many at once; give a line its own delivery if it should be read differently.

  • soundbox.update_line

    Changes a line's words, voice, delivery, or where it sits in time. Changing words or delivery means the line has to be re-read before it is heard.

  • soundbox.speak_storyslow

    Reads every line that has no audio yet, in its assigned voice, one at a time. This is the slowest tool.

  • soundbox.delete_linedestructive

    Removes one line from a story. Its audio stays in the library.

  • soundbox.split_line

    Cuts a voiced line at a point in its own audio, giving two clips. The words stay with the first half, because Soundbox cannot tell which words fell on either side of the cut.

  • soundbox.export_storyslow

    Mixes the whole arrangement to one sound, honouring where each clip sits, its trim, its gain, and whether it is muted.

Arrangement

The timeline underneath a story: which lane a clip is on, how loud it is, and what the studio shows when you open it.

  • soundbox.open_in_studio

    Lays a library sound out on a timeline, split into stems on separate tracks where that is possible. If the sound already has stems, it reuses them.

  • soundbox.mix_track

    Controls one lane of a story. These settings belong to the lane; the clips on it keep their own.

  • soundbox.remove_trackdestructive

    Deletes a lane and the clips on it; lanes above slide down. Call soundbox.get_story first if you are not certain what is on it.

The models it reaches

Soundbox runs open-weight models locally and does not train its own. Each model's licence is shown before you download it. The output is yours, and the model's terms govern what you may do with it. list_models reports the same thing as commercial_use, so an agent can check before it generates.

Questions

What is MCP?

The Model Context Protocol is an open standard for giving an AI agent tools it can call. Soundbox runs an MCP server inside its own process, so an agent connected to it can generate sound effects, music and speech, and arrange them, without you leaving the conversation you are already in.

Which clients work with it?

Anything that speaks MCP. Claude Code takes the HTTP URL as a single command; Claude Desktop, Cursor and the rest take a JSON config block with the same URL. Clients that only speak stdio can use the bundled stdio bridge, which proxies onto the running server and loads no models itself.

Do I need an API key?

No. There is no key and no account, because there is no auth and no cloud: the server listens on 127.0.0.1 and the agent runs on the same machine. Over HTTP there is nothing to install on the agent's side.

What does it cost per generation?

Nothing. Generation runs on your own GPU from open-weight models you have downloaded, so there is no per-second billing and no subscription for model access. Soundbox itself is MIT-licensed.

How long does a generation take?

Seconds to a minute, depending on the model and the length of the clip. The tool call blocks until the audio is written to disk, so the agent receives a finished file and has no job id to poll.

Can I use the output commercially?

It depends on the model. Each model's licence is stated on its page, and the list_models tool reports commercial_use as yes, no or conditional, so an agent working on something commercial can check before it generates.

Does anything leave my machine?

No. The weights are on your disk, the inference runs on your machine, and the WAV is written to your filesystem.

Can I use it with my own agent?

Yes. Any MCP client can connect over HTTP with the same URL; nothing in the server is Claude-specific. To skip MCP, call the HTTP API that the same local server exposes.

Do I need to keep the app open?

Yes. The MCP server runs inside the main Soundbox process, so there is no separate daemon to start. If the app is running, the tools are available. If it is not, the tools return an actionable error; they do not start a second copy that would compete for the GPU.

Connect itRead the tool reference