🎙️ mac-voice-mcp

Talk with Claude out loud on your Mac.
Natural turn-taking · on-device speech recognition · no audio leaves your computer

Claude says something 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 Mac

It's built for Apple Silicon Macs (M1–M4). Linux works too, with SoX and espeak-ng installed.

🤖 Vibe-coded

This project was designed and written with Claude, in conversation. A human (me) steered it, tried it on a real Mac and checked the test suite, but most of the code was written by AI. It's a proof of concept: it works and has tests, but expect rough edges, and read the code before relying on it for anything important. Issues and pull requests are welcome.

It's an independent project, not made or endorsed by Anthropic. It works with any MCP client, including Claude Desktop, Claude Code and Cursor.

How it works

The server has two tools and two prompts:

Listening works like a conversation. A soft chime plays when the mic opens. The server waits for you to start talking and hands back to Claude about a second after you stop. It adjusts to background noise, doesn't cut you off at pauses mid-sentence, and ignores coughs and clicks. If you say nothing for 15 seconds, Claude gets "no speech", which it is told never to treat as a yes.

Replies come back fast. whisper.cpp's server keeps the speech model loaded between turns, and the model starts loading while Claude is still talking. You don't wait for a model load on each reply. After 15 idle minutes the server shuts down to free memory. It is stopped automatically even if the MCP server crashes.

Claude sends text meant to be heard. The tool description gives Claude rules for writing short spoken sentences. If code, paths, links or markdown still get through, the server rewrites them before speaking and tells Claude, so the next message is cleaner. See below.

Install

You need Node.js 22 or newer. Whichever way you install, run setup once afterwards (see Then, below).

One click

From a marketplace

• Claude Code plugin marketplace. This repo is its own marketplace:
  Code

  Copy

  /plugin marketplace add jeet0007/mac-voice-mcp
  /plugin install mac-voice-mcp@mac-voice-mcp
  

  The plugin adds /mac-voice-mcp:setup and /mac-voice-mcp:talk, a skill that teaches Claude how to use voice well and fix common problems, and a hook that keeps a voice conversation in voice (see Voice mode). Each plugin version runs the matching npm release.
• The official MCP Registry. It's listed as io.github.jeet0007/mac-voice-mcp. Apps and directories that read the registry pick it up from there. In VS Code, open the Extensions view (⇧⌘X), search @mcp mac-voice, and click Install. Smithery, Glama, PulseMCP and mcp.so copy the registry, so it shows up there too.

By hand

Claude Code

claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp@latest

Claude Desktop. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then quit (⌘Q) and reopen the app:

{
  "mcpServers": {
    "voice-mcp": {
      "command": "npx",
      "args": ["-y", "mac-voice-mcp@latest"]
    }
  }
}

@latest makes npx check for a new release each time the app starts. Without it, npx keeps running whichever version it cached first.

If you get spawn npx ENOENT, use the full path from which npx, e.g. "command": "/opt/homebrew/bin/npx".

Cursor. Add the same mcpServers block to ~/.cursor/mcp.json.

VS Code. Run MCP: Add Server from the Command Palette, or:

code --add-mcp '{"name":"voice-mcp","command":"npx","args":["-y","mac-voice-mcp@latest"]}'

Any other MCP client. Run npx -y mac-voice-mcp@latest as a stdio server.

Then: set up and allow the mic

Run setup once. Ask Claude to "set up voice". In Claude Code you can also run /mac-voice-mcp:setup (plugin) or /mcp__voice-mcp__setup (added by hand), or from a terminal run npx -y mac-voice-mcp@latest setup.

Setup checks what's already there before it changes anything:

• Nothing is redone. Tools already on your PATH are used as they are. If the model is already somewhere on disk (a whisper.cpp checkout, Homebrew's share folder, another tool's cache, or anything Spotlight can find), it's symlinked, not downloaded again. brew install runs only for the missing formulae.
• Nothing happens without your OK. Claude calls voice_setup to check first, shows you the checklist, and asks before calling it with install=true.
• Slow installs don't time out. If brew install whisper-cpp takes a while, setup reports INSTALLING. The install carries on in the background, and the next check picks up the result.

Allow the microphone. The first time Claude listens, macOS asks whether Claude (or Cursor, or your terminal) can use the microphone. Click Allow.

Get a better voice (recommended). macOS includes free Premium voices that sound far more natural than the default. Open System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…, and download one, for example English → Ava (Premium) or Zoe (Premium). The next voice turn uses it automatically. To choose a specific voice, or keep the system voice, see VOICE_MCP_VOICE under Configuration.

Allow voice turns without prompts

By default, 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 the permissions.allow list in ~/.claude/settings.json. Use the name that matches how you installed it: