MCP 服务器

Voice MCP

Enables bidirectional voice interaction for Claude Code using local speech-to-text and text-to-speech models optimized for Apple Silicon. It provides tools to listen to user speech via microphone and speak responses aloud through system speakers.

README

voice-mcp

Bidirectional voice MCP server for Claude Code. Adds listen() and speak() tools so Claude can hear you and talk back — all running locally on Apple Silicon via mlx-audio.

User speaks → listen() → mic + VAD → Voxtral Realtime STT → text to Claude
Claude responds → speak(text) → Kokoro TTS → AudioPlayer → speakers

Requirements

macOS with Apple Silicon (M1+)
Python 3.11+
uv
A working microphone and speakers

Setup

git clone <this-repo> && cd voice-mcp
uv sync

First run downloads the models from HuggingFace (~2.5 GB total):

STT: mlx-community/Voxtral-Mini-4B-Realtime-2602-int4 (Voxtral Realtime, 4-bit quantized)
TTS: mlx-community/Kokoro-82M-bf16 (Kokoro, 82M params)

Configure Claude Code

The repo includes .mcp.json so Claude Code auto-discovers the server. Just open Claude Code from the project directory:

cd voice-mcp
claude

On first use, Claude Code will prompt you to approve the MCP server.

To use from a different project, add to that project's .mcp.json:

{
  "mcpServers": {
    "voice": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/voice-mcp", "run", "server.py"]
    }
  }
}

Usage

Voice input

Tell Claude "listen to me" or use the /listen slash command. You'll hear a rising chime when the mic is active — speak naturally, and recording stops automatically after 1.5s of silence (falling chime).

Voice output

Claude will speak conversational responses automatically. Code, data, and technical details stay in the terminal.

Change voice

Use /voice to browse all 54 available voices across 9 languages, or /voice am_echo to switch directly.

Tools

`listen(duration?)`

Records audio from the microphone and returns a transcription.

Default: VAD-based — waits for speech, stops after silence
With duration: fixed-length recording (seconds)
STT languages: ar, de, en, es, fr, hi, it, ja, ko, nl, pt, ru, zh

`speak(text, voice?, speed?, lang?)`

Speaks text aloud through the computer's speakers.

voice: Kokoro voice ID (default: af_heart). See /voice for options
speed: playback speed multiplier (default: 1.0)
lang: language code — a American English, b British English, e Spanish, f French, h Hindi, i Italian, j Japanese, p Portuguese, z Mandarin

How it works

The server runs as a stdio subprocess managed by Claude Code. Audio I/O (mic + speakers) happens in the server process; only text crosses the MCP protocol.

STT: Voxtral Realtime (4B params, int4) — streams audio through a causal encoder-decoder with adaptive RMS normalization
TTS: Kokoro (82M params, bf16) — ALBERT text encoder → prosody predictor → iSTFTNet vocoder
VAD: webrtcvad (mode 3) with energy-based fallback
Audio cues: synthesized tones via sounddevice — rising chime = listening, falling chime = done
Notifications: macOS banners via hooks when listening starts/stops and when speaking

Models are pre-loaded at server startup via FastMCP's lifespan hook, so the first tool call is fast.