mac-voice-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VOICE_MCP_RATE | No | Words per minute, e.g. 200. | system rate |
| VOICE_MCP_CHIME | No | Set to 0 to turn off the mic open/close sounds. | 1 |
| VOICE_MCP_DEBUG | No | Verbose logs with per-turn timings, written to stderr. | 0 |
| VOICE_MCP_VOICE | No | macOS voice, e.g. Samantha, Daniel, Kanya. List them with `say -v '?'`. | system voice |
| VOICE_MCP_THREADS | No | Number of whisper.cpp threads. | min(8, cores) |
| VOICE_MCP_LANGUAGE | No | en, th, ja, de, … | en for *.en models, otherwise auto |
| VOICE_MCP_RECORDER | No | sox or ffmpeg (ffmpeg is macOS only). | auto |
| VOICE_MCP_CACHE_DIR | No | Where models are downloaded or symlinked. | ~/.cache/mac-voice-mcp |
| VOICE_MCP_MIN_SPEECH_DB | No | The quietest level that ever counts as speech (dBFS). | -48 |
| VOICE_MCP_WHISPER_MODEL | No | Which model to use (see the table below). | base.en |
| VOICE_MCP_END_SILENCE_MS | No | How long a pause ends your turn. Use 1800 if it cuts you off while you think, 800 for snappier replies. | 1200 |
| VOICE_MCP_WHISPER_PROMPT | No | Words to bias toward: names, product terms, jargon. | |
| VOICE_MCP_WHISPER_SERVER | No | Set to 0 to always use whisper-cli, with no warm server. | 1 |
| VOICE_MCP_MAX_SPEAK_WORDS | No | Longer text is cut at a sentence boundary ("the rest is on screen"). | 120 |
| VOICE_MCP_SPEECH_MARGIN_DB | No | How much louder than room noise counts as speech. Raise it in noisy rooms. | 12 |
| VOICE_MCP_MODEL_SEARCH_PATHS | No | Extra folders to check for an existing model (`:`-separated). | |
| VOICE_MCP_WHISPER_MODEL_PATH | No | Use this exact ggml-*.bin file. | |
| VOICE_MCP_SERVER_IDLE_MINUTES | No | How long the warm server stays up without use. | 15 |
| VOICE_MCP_START_TIMEOUT_SECONDS | No | How long to wait for you to start talking. | 8 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| speak_and_listen | Say something out loud to the user and hear their spoken reply. Speaks text_to_speak through the computer's speakers, then listens like a conversation turn — it waits for the user to start talking and stops when they finish — and returns an on-device transcript of what they said. Write text_to_speak for the ear, not the screen:
Good: "The build passed and all tests are green. Want me to open the pull request?"
Bad: "## Results\n- Once the user is talking with you by voice, keep the conversation in voice: answer each transcript with another speak_and_listen call (not a text reply) until they say stop or start typing. To end voice mode, or for a one-way announcement, pass listen: false: it returns at once and speaks while you work. A reply of "(No speech detected …)" means the user did not answer — never treat it as consent. Ask once more; if still nothing, stop and say on screen that voice mode is paused and they can type to carry on (not speak: the mic is off). The "voice-mcp timing" line at the end is diagnostics: ignore it unless the user asks why things feel slow. If it reports that voice-mcp is not set up, call voice_setup. |
| voice_setupA | Check whether this computer has everything speak_and_listen needs — text-to-speech, a microphone recorder (SoX),
whisper.cpp speech-to-text and the speech model — and optionally install what's missing.
Anything already installed is reused (an existing model elsewhere on disk is symlinked, not re-downloaded).
Call it with install=false (the default) first and tell the user what is missing.
Only call it with install=true after the user agrees: it runs |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| setup | Check what voice-mcp needs, install what's missing (with your OK), then test it. |
| voice_mode | Hands-free session: Claude checks in out loud via speak_and_listen, using speakable phrasing. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 2 tools
The two tools are unmistakably distinct: voice_setup handles environment provisioning/installation, while speak_and_listen performs the actual speech-and-transcription turn. An agent cannot reasonably confuse a one-time setup check with a conversational I/O call.
Both names are snake_case and readable, but they mix conventions slightly: voice_setup is a noun-style name while speak_and_listen is a verb phrase. The deviation is minor and doesn't hinder comprehension.
Two tools is on the thin side, but the domain (local voice I/O on a Mac) is genuinely narrow, and both tools carry substantial, non-overlapping responsibility. Nothing feels padded or redundant.
Setup plus a bidirectional speak/listen turn covers the core lifecycle, and the descriptions show a speak-only mode via listen=false. Minor gaps exist (no explicit stop/interrupt, voice selection, or device/config listing), but agents can work around them.