How do I install Mac Voice?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Mac Voice need an API key?

The publisher lists these environment variables: VOICE_MCP_WHISPER_MODEL, VOICE_MCP_LANGUAGE, VOICE_MCP_END_SILENCE_MS.

What transport does Mac Voice use?

Mac Voice runs locally over stdio.

When was Mac Voice last checked?

Last checked 2026-11-09. Talk with your AI assistant out loud on a Mac, with on-device speech recognition (whisper.cpp).

Mac Voice MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

VOICE_MCP_WHISPER_MODEL — whisper.cpp model name (default base.en)
VOICE_MCP_LANGUAGE — Spoken language code, e.g. en, th, or auto
VOICE_MCP_END_SILENCE_MS — Pause length that ends your turn, in ms (default 1200)

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1VOICE_MCP_WHISPER_MODEL=<value> VOICE_MCP_LANGUAGE=<value> VOICE_MCP_END_SILENCE_MS=<value> claude mcp add io.github.jeet0007-mac-voice-mcp -- npx -y mac-voice-mcp@0.9.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.jeet0007-mac-voice-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "VOICE_MCP_WHISPER_MODEL": "<value>",11        "VOICE_MCP_LANGUAGE": "<value>",12        "VOICE_MCP_END_SILENCE_MS": "<value>"13      }14    }15  }16}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.9.0

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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 Mac

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

Features

🔒 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 1.5 seconds 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).
🫧 Voice Buddy (optional, Claude Code). An animated buddy above the prompt shows when Claude is speaking or listening, and your first keystroke interrupts it.
🪟 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.

Quick start

You need a Mac (Apple Silicon recommended) and Node.js 22 or newer.

1. Install.

Claude Code (recommended). Install the plugin, and Voice Buddy with it:
```
/plugin marketplace add jeet0007/mac-voice-mcp
/plugin install mac-voice-mcp@mac-voice-mcp
/plugin install voice-buddy@mac-voice-mcp
```
Voice Buddy is optional: it adds the animated buddy above the prompt and lets you interrupt by typing (more).
Cursor 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.

Allow voice turns without prompts

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.

How it works

The server has two tools and two prompts:

	What it does
`speak_and_listen`	Speaks a short message, listens for one conversational turn and returns the transcript.
`voice_setup`	Checks what's installed. After you agree, it installs only what's missing.
`setup` prompt	A guided setup: it checks, asks you, installs, then runs a spoken test.
`voice_mode` prompt	A hands-free session where Claude checks in by voice at natural points.

Claude is told to write for the ear: short sentences, no markdown, file names instead of paths. Anything that slips through is rewritten before it's spoken. In Claude Code, the plugin keeps a voice conversation in voice until you type. More in Using it.

Troubleshooting

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 `VOICE_MCP_END_SILENCE_MS=2000`.
The voice sounds robotic	Download a Premium macOS voice or install Kokoro. See Voices.
It asks for approval every turn	See Allow voice turns without prompts.

Documentation

Install: every app, the MCP Registry, installing from a clone, upgrading.
Voices: macOS Premium voices and the optional Kokoro voice.
Using it: voice mode, talking while Claude works, Voice Buddy, several sessions.
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.
Changelog

🤖 Vibe-coded

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.

Disclaimer

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.

Third-party software

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
SoX	Recording from the mic, Kokoro playback	GPL-2.0
whisper.cpp	Speech-to-text	MIT
Whisper models (OpenAI)	Speech-to-text	MIT
macOS voices (`say`)	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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Mac Voice?

Does Mac Voice need an API key?

What transport does Mac Voice use?

When was Mac Voice last checked?

Documentation

Features

Quick start

Allow voice turns without prompts

How it works

Troubleshooting

Documentation

🤖 Vibe-coded

Disclaimer

Third-party software

License