Skip to main content
Glama

VoiceMode

Natural voice conversations with Claude Code (and other MCP capable agents)

New, 9 Nov 2026: Session Kit, from the people who brought you VoiceMode. A voice, a phone line and mail for your Claude Code sessions. Works on macOS; preliminary testing on Linux.

PyPI Downloads PyPI Downloads PyPI Downloads

VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.

Perfect for:

  • Walking to your next meeting

  • Cooking while debugging

  • Giving your eyes a break after hours of screen time

  • Holding a coffee (or a dog)

  • Any moment when your hands or eyes are busy

See It In Action

VoiceMode Demo

Related MCP server: Voice Call MCP Server

Quick Start

Requirements: Computer with microphone and speakers

The fastest way for Claude Code users to get started:

# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode

# Install VoiceMode plugin
claude plugin install voicemode@voicemode

## Install dependencies (CLI, Local Voice Services)

/voicemode:install

# Start talking!
/voicemode:converse

Option 2: Python installer package

Installs dependencies and the VoiceMode Python package.

# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install

# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher

# Optional: Add an OpenAI API key as a fallback for local services.
# A Kokoro voice (af_sky, ...) is not swapped for an OpenAI one by default;
# set VOICEMODE_TTS_VOICE_SUBSTITUTION=true if you want that.
export OPENAI_API_KEY=your-openai-key

# Start a conversation
claude converse

For manual setup, see the Getting Started Guide.

Features

  • Natural conversations - speak naturally, hear responses immediately

  • Works offline - optional local voice services (Whisper STT, Kokoro TTS)

  • Low latency - fast enough to feel like a real conversation

  • Smart silence detection - stops recording when you stop speaking

  • Privacy options - run entirely locally or use cloud services

Compatibility

Platforms: Linux, macOS, Windows (native or WSL), NixOS Python: 3.10-3.14

Configuration

VoiceMode works out of the box. For customization:

# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"

# Or configure via file
voicemode config edit

See the Configuration Guide for all options.

Permissions Setup (Optional)

To use VoiceMode without permission prompts, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

See the Permissions Guide for more options.

Local Voice Services

For privacy or offline use, install local speech services:

These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.

Installation Details

Ubuntu/Debian

sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev

WSL2 users: The pulseaudio packages above are required for microphone access.

Fedora/RHEL

sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel

macOS

brew install ffmpeg node portaudio

NixOS

# Use development shell
nix develop github:mbailey/voicemode

# Or install system-wide
nix profile install github:mbailey/voicemode

From source

git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .

NixOS system-wide

# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

Troubleshooting

Problem

Solution

No microphone access

Check terminal/app permissions. WSL2 needs pulseaudio packages.

UV not found

Run curl -LsSf https://astral.sh/uv/install.sh | sh

OpenAI API error

Verify OPENAI_API_KEY is set correctly

No audio output

Check system audio settings and available devices

Save Audio for Debugging

export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/

Documentation

Full documentation: voicemode.dev

License

MIT - A Failmode Project


mcp-name: dev.voicemode/voicemode

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that integrates high-quality text-to-speech capabilities with Claude Desktop and other MCP-compatible clients, supporting multiple voice options and audio formats.
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP (Model Context Protocol) server that provides seamless integration between Fish Audio's Text-to-Speech API and LLMs like Claude, enabling natural language-driven speech synthesis.
      2
      181 npm
      16
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A local voice interface providing high-performance speech recognition and natural text-to-speech with voice cloning capabilities. It enables AI assistants to speak, listen, and engage in character-based voice conversations through integrated MCP tools.
      -