MCP Voice Hooks

🚀 Voice Mode for Claude Code

Voice Mode for Claude Code enables hands - free, continuous two - way conversations with Claude Code. It leverages the new Claude Code hooks to deliver voice input to Claude during its operation, allowing seamless interaction.

🚀 Quick Start

Voice Mode for Claude Code allows you to communicate with Claude Code hands - free. Here's how to get started:

✨ Features

• Continuous Interaction: Use voice to have an uninterrupted conversation with Claude Code, interrupting, redirecting, or providing feedback without pausing Claude's work.
• Text - to - Speech Option: Optionally enable text - to - speech so that Claude can speak back to you.
• Browser - Based: Voice recognition and text - to - speech are handled by the browser, eliminating the need for downloads or API keys.

📦 Installation

Installation is straightforward:

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Install Voice Mode

npx mcp-voice-hooks@latest install-hooks
claude mcp add voice-hooks npx mcp-voice-hooks@latest

💻 Usage Examples

Basic Usage

1. Start Claude Code

claude

2. Start Listening

The browser interface will automatically open after 3 seconds (http://localhost:5111). Click "Start Listening".

3. Speak

Say something to Claude. You need to send one message in the Claude Code CLI to start the conversation.

Advanced Usage

Trigger Word Mode (Optional)

By default, utterances are sent automatically when you pause. You can switch to "Wait for Trigger Word" mode in the browser interface:

1. Toggle to "Wait for Trigger Word" mode.
2. Enter a trigger word (e.g., "send", "claude", "go").
3. Speak your message(s) - they will queue up in the browser.
4. Say your trigger word to send all queued messages at once (or click "Send Now").

The trigger word is case - insensitive and will be automatically removed from your message before sending.

📚 Documentation

Browser Compatibility

Voice responses

There are two options for voice responses:

1. Browser Text - to - Speech
2. System Text - to - Speech

Selecting and downloading high quality System Voices (Mac only)

Mac has built - in text to speech, but high quality voices are not available by default. You can download high quality voices from the system voice menu: System Settings > Accessibility > Spoken Content > System Voice Click the info icon next to the system voice dropdown. Search for "Siri" to find the highest quality voices. You'll have to trigger a download of the voice. Once it's downloaded, you can select it in the Browser Voice (Local) menu in Chrome. Test it with the bash command:

say "Hi, this is your Mac system voice"

To use Siri voices with voice - hooks, you need to set your system voice and select "Mac System Voice" in the voice - hooks browser interface. Other downloaded voices will show up in the voice dropdown in the voice - hooks browser interface so you can select them there directly, instead of using the "Mac System Voice" option.

⚠️ Important Note

There is a bug in Safari that prevents browser text - to - speech from loading high - quality voices after browser restart. This is a Safari Web Speech API limitation. To use high - quality voices in Safari you need to set your system voice to Siri and select "Mac System Voice" in the voice - hooks browser interface.

Manual Hook Installation

The hooks are automatically installed/updated when the MCP server starts. However, if you need to manually install or reconfigure the hooks:

npx mcp-voice-hooks install-hooks

This will configure your project's .claude/settings.local.json with the necessary hook commands.

Uninstallation

To completely remove MCP Voice Hooks:

# Remove from Claude MCP servers
claude mcp remove voice-hooks

# Also remove hooks and settings
npx mcp-voice-hooks uninstall

This will:

• Clean up voice hooks from your project's .claude/settings.local.json
• Preserve any custom hooks you've added

Configuration

Port Configuration

The default port is 5111. To use a different port, set the MCP_VOICE_HOOKS_PORT environment variable in your project's .claude/settings.local.json:

{
  "env": {
    "MCP_VOICE_HOOKS_PORT": "8080"
  }
}

This environment variable is used by both:

• The MCP server to determine which port to listen on
• The Claude Code hooks to connect to the correct port

💡 Usage Tip

Setting this in .claude/settings.local.json is the recommended approach. The environment variable will be available to both the MCP server process and the hook commands.

Browser Auto - Open

When running in MCP - managed mode, the browser will automatically open if no frontend connects within 3 seconds. To disable this behavior:

{
  "env": {
    "MCP_VOICE_HOOKS_AUTO_OPEN_BROWSER": "false"
  }
}

Experimental: Alternate Installation Method - Plugin mode

Simply add the following to your project's .claude/settings.local.json and restart Claude Code:

{
  "extraKnownMarketplaces": {
    "mcp-voice-hooks-marketplace": {
      "source": {
        "source": "git",
        "url": "https://github.com/johnmatthewtennant/mcp-voice-hooks.git"
      }
    }
  },
  "enabledPlugins": {
    "mcp-voice-hooks-plugin@mcp-voice-hooks-marketplace": true
  }
}

Set enabled to false if you want to temporarily disable the plugin.

Demo Video