@jleelove/voice-mcp
v0.5.0
Published
Local MCP server for the Voice API (Chatterbox TTS + Whisper STT). Runs on your machine, reads local audio files, and streams them to the HTTP API — so large files never pass through the model's context.
Maintainers
Readme
@jleelove/voice-mcp
A local MCP server for the Voice API
(Chatterbox TTS + Whisper large-v3 STT).
Why a local server?
The Voice API itself runs remotely (on the GPU box). A remote MCP server can't touch your machine — it can neither read your local files nor play audio on your speakers. So transcribing a local recording through it means base64-encoding the audio into a tool call (megabytes through the model's context, breaks past a few seconds), and synthesized speech has to be piped back yourself.
This server runs on your machine, so it can:
- Transcribe a local file by path — streamed straight to the API as a multipart upload; the audio never passes through the model, so files of any length work.
- Play synthesized speech on your speakers itself —
synthesizeauto-plays by default; the model just asks for audio. - Add or clone voices from local clips —
upload_voiceregisters a local audio file as a permanent named voice, andsynthesize'ssample_pathreads text in a one-off voice from a clip without saving it.
Local (this) vs. remote (
POST /mcp). The Voice API also hosts a remote Streamable-HTTP MCP server at/mcp. Use this local shim when you want the agent to read files on your disk or play audio on your speakers — the common case for a coding assistant on your laptop. Use the remote/mcpendpoint (add it as anhttpMCP server pointing athttps://voice.codingbutter.com/mcp) when the client can't runnpx, or when audio should play on the server host. They expose the same four tools and share the same voice pool. See the repo'sAPI_DOC.mdfor the full HTTP API and the remote-MCP details.
Requirements
- Node 18+ (for
npx—npx -yfetches and runs the server, no install step). - A reachable Voice API and credentials for it (username/password — the same
accounts as the web login / the API's
users.json). - An audio player for local playback (optional; transcription works without one):
- macOS —
afplayis built in, nothing to install. - Linux/Windows — install
ffmpeg(providesffplay):apt install ffmpeg,brew install ffmpeg,dnf install ffmpeg, orchoco install ffmpeg.
- macOS —
Configure your MCP client
Every client launches the same stdio command — npx -y @jleelove/voice-mcp — with
the environment variables below. The only required vars are the API URL and your
credentials; everything else has sensible defaults (see Configuration).
Claude Code
Project-scoped — create .mcp.json in your repo root:
{
"mcpServers": {
"voice": {
"command": "npx",
"args": ["-y", "@jleelove/voice-mcp"],
"env": {
"VOICE_API_URL": "https://voice.codingbutter.com",
"VOICE_API_USER": "admin",
"VOICE_API_PASSWORD": "your-password"
}
}
}
}Or via the CLI (user-scoped, available in every project):
claude mcp add voice \
-e VOICE_API_URL=https://voice.codingbutter.com \
-e VOICE_API_USER=admin \
-e VOICE_API_PASSWORD=your-password \
-- npx -y @jleelove/voice-mcpClaude Desktop
Edit the config file (create it if missing), then restart the app:
- macOS —
~/Library/Application Support/Claude/claude_desktop_config.json - Windows —
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"voice": {
"command": "npx",
"args": ["-y", "@jleelove/voice-mcp"],
"env": {
"VOICE_API_URL": "https://voice.codingbutter.com",
"VOICE_API_USER": "admin",
"VOICE_API_PASSWORD": "your-password"
}
}
}
}Cursor / Windsurf / other MCP clients
Any client that speaks MCP over stdio uses the same shape: command npx, args
["-y", "@jleelove/voice-mcp"], and the same env block. Add it to that client's
MCP servers config.
Verify
After adding it, your client should list four tools — transcribe,
synthesize, upload_voice, list_voices. Try: "list the
voices" or "say hello".
Local development: to run your own checkout instead of the published package, point
command/argsat the file directly:"command": "node", "args": ["/path/to/voice-mcp/src/index.mjs"]— edits take effect on the next client reconnect, no republish needed.
Configuration
| Env var | Default | Purpose |
|---|---|---|
| VOICE_API_URL | https://voice.codingbutter.com | Base URL of the Voice API. |
| VOICE_API_USER / VOICE_API_PASSWORD | (none) | Credentials for the API (HTTP Basic — same accounts as the web login / users.json). Required if the API has auth enabled. |
| VOICE_API_KEY | (none) | Sent as X-API-Key if you also gate the API at the edge. |
| VOICE_AUTOPLAY | true | Whether synthesize plays audio by default. Set false on headless/CI/SSH hosts. |
| VOICE_BLOCK | false | Default for wait — block until playback finishes. |
| VOICE_PLAYER | (auto) | Force a player command (e.g. mpv), bypassing detection. |
| VOICE_OVERLAP | interrupt | interrupt (newest line wins) or queue (play in order). |
| VOICE_VOLUME | 1.0 | Default linear gain for ffplay/mpv (the API already loudness-normalizes). synthesize's per-call volume arg overrides it for one utterance. |
| VOICE_DEFAULT_VOICE | (server default) | Voice used when voice is omitted. |
| VOICE_FORMAT | wav | Default container when neither format nor an output_path extension is given. |
| VOICE_TMPDIR / VOICE_TEMP_TTL | <tmp>/voice-mcp / 3600 | Where play-only temp files go, and how long (seconds) before the startup sweep reaps them. |
| VOICE_PRE_HOOKS / VOICE_POST_HOOKS | (none) | Comma-separated lists of JS hook modules, run in order. See Hooks. |
| VOICE_HOOK_DATA | (none) | JSON object of default values handed to every hook as ctx.data. Per-call hook_data merges over it. |
| VOICE_HOOK_DATA_DESC | (generic) | Description shown for the hook_data argument in the tool schema — tell the agent which keys your hooks accept. |
Tools
| Tool | What it does |
|---|---|
| transcribe | Speech → text. Pass a local path (streamed) or a url. Supports language, task (transcribe/translate), and timestamps. |
| synthesize | Text → speech. Plays on your speakers by default (play), and/or saves to output_path (WAV/MP3). wait blocks until playback ends. Set volume (linear gain, ~1.0) to override VOICE_VOLUME for one utterance — louder/softer without changing the saved file. With no output_path it plays from an auto-deleting temp file. Pass sample_path (or sample_url) to clone a one-off voice from a clip for that utterance only — not saved. |
| upload_voice | Add a permanent named voice from a local path (or url). The clip is transcoded to mono 24 kHz MP3 server-side and becomes selectable by name in later synthesize calls. |
| list_voices | List available voices, emotions, and tuning ranges. |
Hooks
Every tool call runs through an Express-style middleware chain: pre-hooks see the request before it leaves for the API, post-hooks see the audio (or the transcript) on the way back. A hook can rewrite arguments, observe, or take over entirely — most usefully, send the audio somewhere other than the local speakers.
"env": {
"VOICE_POST_HOOKS": "/home/me/hooks/remote-play.mjs",
"VOICE_HOOK_DATA": "{\"host\":\"minibeast\",\"player\":\"aplay\"}"
}A hook is a JS module whose default export takes (ctx, next):
export default async function myHook(ctx, next) {
ctx.log(`about to speak: ${ctx.args.text}`);
await next(); // continue the chain (playback still happens)
}Calling next() is what makes a hook transparent. Not calling it makes the
hook terminal — the rest of the chain, including the built-in playback, never
runs, and whatever the hook returns becomes the tool result. That's the whole
mechanism: local playback is simply the last handler in the chain, and a hook
that doesn't call next() has claimed the audio for itself.
The ctx object
| Field | Present | What it is |
|---|---|---|
| ctx.tool | always | synthesize | transcribe | upload_voice | list_voices |
| ctx.phase | always | pre or post |
| ctx.args | always | The tool arguments — mutate these in a pre-hook to rewrite the request |
| ctx.data | always | Per-call hook_data merged over VOICE_HOOK_DATA. Your hook's own config channel |
| ctx.log(msg) | always | Write to stderr (never stdout — that's the JSON-RPC channel) |
| ctx.api | always | { url, headers } — enough to call the API yourself |
| ctx.stream | synthesize post, streaming | Node Readable of raw PCM s16le, 24 kHz, mono |
| ctx.buffer / ctx.audio | synthesize post, full render | The encoded audio Buffer, plus { container, bytes } |
| ctx.path | synthesize post | Where the audio was saved, if output_path was requested |
| ctx.playback | synthesize post | { player, volume, bufferMs, wait } — what playback would use |
| ctx.result | post | The result object for non-audio tools (transcript, voice list) |
synthesize takes the streaming path (ctx.stream) unless the call needs a
complete file — an output_path, or an MP3 — in which case you get ctx.buffer.
Handle both if your hook must work for every call.
A file you asked for is always written before post-hooks run. output_path
is part of the request, not part of playback, so a terminal hook can't silently
swallow it.
Shipped example: play on another machine
hooks/remote-play.mjs pipes the PCM stream over SSH
into a player on a different host — so an agent running on a headless build box
speaks out of the laptop on your desk:
"VOICE_POST_HOOKS": ".../node_modules/@jleelove/voice-mcp/hooks/remote-play.mjs",
"VOICE_HOOK_DATA": "{\"host\":\"minibeast\"}"Set host to "local" (or omit it) and the hook calls next(), restoring
normal local playback — so the same config works on both machines.
Hooks are trusted code,
hook_datais not. The agent can sethook_dataon any call, so treat those values as untrusted input:remote-play.mjsregex-validateshostand allowlistsplayerprecisely because a value like-oProxyCommand=…would otherwise be an argv injection againstssh.
Failure behaviour
A hook that throws aborts the call and reports which module failed — hooks
are load-bearing, so they fail loudly rather than being skipped. A hook path
that can't be loaded at startup logs a warning and is dropped; the tools keep
working without it. hook_data only appears in the tool schema when hooks are
actually configured.
Examples (natural language to your agent)
- "Say 'the build is green' in the Will_Wheaton voice." → plays on your speakers.
- "Read this paragraph aloud and also save it as
note.mp3." - "Add
~/clips/jamie.wavas a voice called Jamie." →upload_voice. - "Read this in the voice from
/tmp/grandpa.m4a." → one-offsample_path, not saved. - "Transcribe
~/recordings/standup.m4a." - "Transcribe this Spanish clip and translate it to English:
/tmp/es.mp3."
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| 401 unauthorized — set VOICE_API_USER and VOICE_API_PASSWORD | The API requires auth. Set both env vars to a valid users.json account. |
| Tools listed, but "say hello" produces no sound | No audio player on PATH. Install ffmpeg (gives ffplay), or set VOICE_PLAYER. On a headless/SSH/CI host, set VOICE_AUTOPLAY=false and save with output_path instead. |
| No MP3-capable player found | pw-play/paplay/aplay can't decode MP3. Install ffmpeg/mpv, or synthesize with format="wav". |
| Playback is choppy on a slow link | Raise the pre-buffer: pass buffer_ms (e.g. 800–1500) on the call, or set VOICE_STREAM_BUFFER_MS. |
| Speech too quiet/loud | Pass volume per call (linear gain; 1.0 unchanged) or set VOICE_VOLUME. |
| Server can't be reached | Check VOICE_API_URL and that the API is up: curl $VOICE_API_URL/healthz. |
| Hook configured but nothing changed | The result text lists any [hook warnings] (bad path, failed import). Also check the startup line on stderr for the loaded hook count. |
| Audio stopped playing locally after adding a hook | That's a terminal hook working as designed — it didn't call next(), so built-in playback never ran. Call next() to keep local playback. |
The server logs to stderr (stdout is the JSON-RPC channel and must stay
byte-clean). If a client shows the server as failed, run the launch command by
hand to see the startup line: VOICE_API_URL=… npx -y @jleelove/voice-mcp.
See also
API_DOC.md— the full Voice API this shim calls (REST + WebSockets), and the remotePOST /mcpserver.
License
MIT
