Talk with Claude out loud on your Mac — it speaks through your speakers, listens to your reply, and returns an on-device transcript.
speak_and_listen: speaks a message aloud, then listens for one conversational turn (no push-to-talk) and returns the transcript.
Auto-formats speech for the ear — short plain sentences, no markdown, code, paths or URLs.
listen: false — one-way announcement, or a goodbye, without opening the microphone.
listen_seconds — optional upper limit on listening time (default 30s, max 120s).
voice_setup — checks for text-to-speech, SoX, whisper.cpp and a speech model, reusing anything already installed.
voice_setup with install: true — installs missing Homebrew packages and downloads the model, only after you agree.
voice_setup with kokoro: true — optionally installs the more natural Kokoro neural voice (~1 GB, runs locally).
Supports hands-free voice sessions and turn-taking across multiple apps/windows, all speech recognition staying on your Mac.
Uses the Mac's built-in text-to-speech (say with installed system voices, including Premium voices) to speak messages aloud, and captures microphone audio for on-device speech recognition, providing a natural spoken conversational turn between Claude and the user.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mac-voice-mcp ask me if I'm ready to deploy the app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude speaks through your Mac's speakers, listens to your answer the way a person would, and gets back what you said as text. Speech recognition runs on your Mac, so no audio leaves your computer.
Claude ──speak_and_listen("Tests pass. Open the PR?")──▶ 🔊 "Tests pass. Open the PR?"
🎙 you: "yes, and tag Priya"
Claude ◀──────────────── "Yes, and tag Priya." ───────── whisper.cpp on your MacPerfect for:
Long tasks: Claude works quietly and checks in out loud when it needs a decision, so you can step away from the screen.
Quick reviews: a 20-second summary of a pull request, then "approve it?"
Resting your eyes, or your wrists, after a long day at the keyboard.
Thinking out loud: talking a problem through instead of typing it.
🔒 On-device. whisper.cpp transcribes on your Mac. Recordings are deleted after each turn.
💬 Natural turn-taking. A soft chime, then it waits for you to start, and hands back about a second after you stop. No push-to-talk.
⚡ Fast replies. A warm whisper.cpp server keeps the model loaded, so transcribing takes a fraction of a second on Apple Silicon.
🗣️ A natural voice, if you want one. Uses your best macOS voice, or the optional Kokoro neural voice.
✋ Asks before installing anything. Setup checks what you already have and reuses it.
🙋 Talk while Claude works. Say "Claude, use the other branch" mid-task and it takes it into account at its next step (Claude Code plugin).
🪟 One mic, many windows. Claude Code, Claude Desktop and Cursor take turns instead of talking over each other.
📏 Measured, not guessed. doctor checks the whole pipeline on your Mac and scores it PASS, WARN or FAIL.
Related MCP server: Voice MCP
You need a Mac (Apple Silicon recommended) and Node.js 22 or newer.
1. Install.
Claude Code (recommended). Install the plugin:
/plugin marketplace add jeet0007/mac-voice-mcp
/plugin install mac-voice-mcp@mac-voice-mcpCursor or VS Code:
Claude Desktop and other apps: add npx -y mac-voice-mcp@latest as a stdio MCP server. See Install for each app.
2. Set up. Ask Claude to "set up voice" (or run /mac-voice-mcp:setup). It checks for SoX, whisper.cpp and a speech model, shows you what's missing, and installs it only after you say yes.
3. Allow the microphone. The first time Claude listens, macOS asks. Click Allow.
4. Talk. Run /mac-voice-mcp:talk fix the flaky login test, or ask Claude to "check in with me by voice when you need a decision". Reply after the chime.
Claude Code asks for approval every time Claude wants to speak, which breaks the flow of a conversation. To allow voice turns, add the tool to permissions.allow in ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__plugin_mac-voice-mcp_voice-mcp__speak_and_listen",
"mcp__voice-mcp__speak_and_listen"
]
}
}The first name is for the plugin, the second for claude mcp add voice-mcp …. Leave voice_setup out, so installs still ask you first.
The server has two tools and two prompts:
What it does | |
| Speaks a short message, listens for one conversational turn and returns the transcript. |
| Checks what's installed. After you agree, it installs only what's missing. |
| A guided setup: it checks, asks you, installs, then runs a spoken test. |
| A hands-free session where Claude checks in by voice at natural points. |
Claude is told how to write for the ear: short sentences, no markdown, file names instead of paths. If code or links still get through, the server rewrites them before speaking. In Claude Code, the plugin also keeps a voice conversation in voice until you type. More in Using it.
Run npx -y mac-voice-mcp@latest doctor first. It tests setup, the voice and transcription, and your speakers and mic, and tells you which part fails.
Symptom | Fix |
"microphone returned pure digital silence" | Allow the mic for the app (Claude, Cursor or your terminal) in System Settings → Privacy & Security → Microphone, then restart it. |
It cuts me off while I'm thinking | Set |
The voice sounds robotic | Download a Premium macOS voice or install Kokoro. See Voices. |
It asks for approval every turn |
More in Troubleshooting.
Install: every app, the MCP Registry, installing from a clone, upgrading.
Voices: macOS Premium voices and the optional Kokoro voice.
Using it: voice mode, several sessions, getting Claude to sound natural.
Configuration: every setting, and the speech models.
Troubleshooting: common problems and known limitations.
Privacy and security: what stays on your Mac, and how the project is secured.
Development: building, testing and releasing.
This project was designed and written with Claude, in conversation. A human (me) steered it, tested it on a real Mac and checked the test suite, but most of the code was written by AI. Read the Disclaimer before you rely on it.
mac-voice-mcp is a free, open-source personal project. It's provided as is, with no warranty of any kind, and the authors aren't liable for any damage or loss from using it. See the LICENSE for the exact terms. In plain words:
It turns on your microphone whenever an AI assistant calls speak_and_listen, and plays sound through your speakers.
Speech recognition makes mistakes. An assistant may act on a misheard word. Check what it heard before you let it do anything you can't undo, like deleting files, pushing code or sending messages.
It installs software on your Mac, but only after you agree: Homebrew packages, and kokoro-js with npm if you choose the Kokoro voice. Those are separate projects, under their own licenses (below).
There's no guaranteed support. Issues and pull requests are welcome, and fixed on a best-effort basis.
Trademarks. Apple, Mac, macOS and Siri are trademarks of Apple Inc. Claude is a trademark of Anthropic. mac-voice-mcp is an independent project, not affiliated with, sponsored or endorsed by Apple or Anthropic.
mac-voice-mcp doesn't bundle any of these. It uses them when they're on your Mac, and installs them only with your consent. Each one comes under its own license.
Software | Used for | License |
Recording from the mic, Kokoro playback | GPL-2.0 | |
Speech-to-text | MIT | |
Whisper models (OpenAI) | Speech-to-text | MIT |
macOS voices ( | The built-in voice | Apple's macOS license |
kokoro-js (optional) | The Kokoro voice | Apache-2.0 |
Kokoro-82M model (optional) | The Kokoro voice | Apache-2.0 |
espeak-ng (optional, inside kokoro-js) | Turning text into sounds for Kokoro | GPL-3.0 |
ffmpeg (fallback, never installed by setup) | Recording, if SoX is missing | LGPL-2.1 / GPL |
MIT © Jeet
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:
1–3 short sentences, under ~40 words; lead with the outcome, then one question.
Plain words only: no markdown, bullets, emoji, code, file paths, URLs, stack traces or tables.
Describe code instead of reading it ("I added a retry to the upload function"), say file names not paths ("in index.ts"), round numbers ("about two hundred ms"), spell out symbols.
Ask one question at a time, answerable in a few words ("Should I deploy it — yes or no?").
Put the details (diffs, logs, links) in your normal on-screen reply, and say so out loud.
Tool output (Bash stdout, file writes) is NOT the on-screen reply. Only your own assistant message text renders.
A spoken turn with no assistant message text shows the user nothing — never skip the on-screen reply.
Good: "The build passed and all tests are green. Want me to open the pull request?"
Bad: "## Results\n- npm test ✅ 42/42\n- see /Users/x/repo/src/index.ts:120"
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.
| Name | Required | Description | Default |
|---|---|---|---|
| listen | No | Default true. false: only speak, without opening the microphone — for a one-way announcement, or to say goodbye when the user ends voice mode. It returns right away and speaks while you carry on. | |
| text_to_speak | Yes | The summary or message to read aloud to the user. Plain, conversational text. | |
| listen_seconds | No | Upper limit on how long to listen, in seconds (default 30, max 120). Listening already stops when the user finishes talking, so you rarely need this. |
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 brew install for the missing packages
and downloads the speech model once. It never uninstalls or changes anything else.
kokoro=true (also only after the user agrees) installs the optional Kokoro voice: more natural than the built-in one,
runs on this Mac, about 1 GB on disk. Once installed it's used automatically; the built-in voice stays as the fallback.
If it reports INSTALLING, the install continues in the background — wait a minute and call it again to check.
| Name | Required | Description | Default |
|---|---|---|---|
| kokoro | No | true: install the optional Kokoro voice — a natural-sounding neural voice that runs on this Mac (kokoro-js via npm and a one-time model download, about 1 GB on disk). Ask the user first. | |
| install | No | false (default): only check. true: brew install missing packages and download the model. Ask the user first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: existing installs are reused, an existing model is symlinked rather than re-downloaded, brew install runs and the model downloads once, nothing is uninstalled, and it discloses the background INSTALLING state plus the need to re-poll. This is consistent with idempotentHint=true and destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose, then the consent workflow, then the optional kokoro path and the INSTALLING caveat. Slightly long and dense with parentheticals, but each sentence carries distinct operational information and none is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a hint of the return status, the description compensates by explaining the INSTALLING condition and the re-check loop, so an agent knows what a call will produce and how to proceed. The consent contract and platform assumptions (brew, this Mac) are fully covered for a two-boolean provisioning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the parameters are documented. The description still adds real meaning the schema lacks: kokoro's size (~1 GB), that it becomes the automatic voice with the built-in one as fallback, and that install=true performs brew install/download in the background. It mostly enriches rather than restating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (check/install the dependencies speak_and_listen needs) and enumerates exactly which components are involved (TTS, SoX recorder, whisper.cpp, speech model). This clearly distinguishes it from its only sibling, speak_and_listen, which uses rather than provisions those components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit ordered workflow: call with install=false first and report gaps to the user, only use install=true after user agreement, and only enable kokoro after separate agreement. The when-not conditions (before consent) are stated, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.0speak_and_listen1 field changedInput schema / properties / listen / descriptionPrevious value: -"Default true. false: only speak, without opening the microphone — for a one-way announcement, or to say goodbye when the user ends voice mode."New value: +"Default true. false: only speak, without opening the microphone — for a one-way announcement, or to say goodbye when the user ends voice mode. It returns right away and speaks while you carry on."v0.4.0voice_setup1 field changedInput schema / properties / kokoroAdded value: +{
+ "description": "true: install the optional Kokoro voice — a natural-sounding neural voice that runs on this Mac (kokoro-js via npm and a one-time model download, about 1 GB on disk). Ask the user first.",
+ "type": "boolean"
+}v0.3.1speak_and_listen1 field changedInput schema / properties / listenAdded value: +{
+ "description": "Default true. false: only speak, without opening the microphone — for a one-way announcement, or to say goodbye when the user ends voice mode.",
+ "type": "boolean"
+}v0.1.0speak_and_listenvoice_setupScored 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.
Let cloud agents talk to you: progress updates spoken on your Mac, and replies you send back.
Claude makes real phone calls for you — in many languages, with transcript and outcome back in chat.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Ask Claude about your meetings: summaries, action items and transcripts from Roomtone
