Voice

Bidirectional voice MCP server enabling local listen and speak interactions with Claude Code using on-device STT and TTS.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "shreyaskarnik-voice-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/voice-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "ENV_EXAMPLE": "YOUR_VALUE"
      }
    }
  }
}

You can run a bidirectional voice MCP server locally to let Claude Code hear you and talk back. It uses a local microphone and speakers, with on-device speech-to-text and text-to-speech, so your conversations with Claude stay private to your machine.

How to use

Use a compatible MCP client to connect to the voice MCP server running locally. You will interact through Claude Code where you can start listening, speak, and hear Claude’s responses.

How to install

Prerequisites you need on your machine:

macOS with Apple Silicon (M1 or newer)
Python 3.11 or newer
uv (the MCP runner)
a working microphone and speakers

Set up the repository and bootstrap the MCP server locally by running these commands in your terminal:

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

The first run downloads the necessary model files (approximately 2.5 GB total). You’ll get the STT and TTS models ready for real-time processing.

Configure Claude Code to auto-discover the MCP server. Open Claude Code from the voice-mcp project directory and start the server integration:

cd voice-mcp
claude

If you want to run this MCP server from a different project, add the MCP config to that project’s configuration to point to the local server. Use this example configuration snippet in that project’s MCP setup:

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

Additional notes

The server runs as a standard input/output subprocess managed by Claude Code. All audio I/O happens inside the server process; only text travels through the MCP protocol.

Under the hood, it uses Voxtral Realtime for speech-to-text, Kokoro for text-to-speech, and WebRTC Voice Activity Detection to determine when you start and stop speaking. You’ll hear a rising chime when the mic is active and a falling chime when recording finishes.

All model loading happens at startup, so the first tool call will feel fast once the server is ready.

Security and privacy notes

All voice processing happens locally on your machine. No audio data leaves your device unless you explicitly export transcripts or audio.

Available tools

listen

Records audio from the microphone and returns a transcription. Supports a default VAD-based mode or a fixed-duration recording when duration is provided.

speak

Speaks text aloud through the computer speakers with optional voice, speed, and language parameters.

voice

Browse and switch among available TTS voices and languages for spoken responses.