npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.

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 — synthesize auto-plays by default; the model just asks for audio.
  • Add or clone voices from local clips — upload_voice registers a local audio file as a permanent named voice, and synthesize's sample_path reads 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 /mcp endpoint (add it as an http MCP server pointing at https://voice.codingbutter.com/mcp) when the client can't run npx, or when audio should play on the server host. They expose the same four tools and share the same voice pool. See the repo's API_DOC.md for the full HTTP API and the remote-MCP details.

Requirements

  • Node 18+ (for npx — npx -y fetches 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 — afplay is built in, nothing to install.
    • Linux/Windows — install ffmpeg (provides ffplay): apt install ffmpeg, brew install ffmpeg, dnf install ffmpeg, or choco install ffmpeg.

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-mcp

Claude 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/args at 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_data is not. The agent can set hook_data on any call, so treat those values as untrusted input: remote-play.mjs regex-validates host and allowlists player precisely because a value like -oProxyCommand=… would otherwise be an argv injection against ssh.

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.wav as a voice called Jamie." → upload_voice.
  • "Read this in the voice from /tmp/grandpa.m4a." → one-off sample_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 remote POST /mcp server.

License

MIT