Voice Loop

Provides a self-sustaining voice conversation loop with Claude Code for hands-free AI dialogue.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 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": {
    "theonlypal-voice-loop-mcp": {
      "command": "python",
      "args": [
        "-m",
        "voice_loop_mcp"
      ]
    }
  }
}

Voice Loop MCP lets you run a self-sustaining, hands-free voice conversation loop with Claude Code. You speak and Claude listens, responds (via text or text-to-speech), and keeps the loop alive through self-prompting. It’s designed for seamless, ongoing dialogue without keyboard input, once you have it up and running on your macOS machine.

How to use

Set up the Voice Loop MCP in your Claude Code environment to enable a continuous, voice-driven chat with Claude. You’ll configure a local MCP server, start listening for speech, and let Claude read your speech and reply in real time. Use the provided tools to control the loop, read transcriptions, and keep the conversation alive.

How to install

Prerequisites you need to meet before installing shows up here.

# 1) Install Voice Loop MCP locally
cd voice-loop-mcp
pip install -e .

# 2) Install the 'hear' CLI
./scripts/install_hear.sh
# Grant microphone permission when prompted

Next, add the Voice Loop MCP to Claude Code so you can start the loop from your client.

{
  "mcpServers": {
    "voice_loop": {
      "command": "python",
      "args": ["-m", "voice_loop_mcp"]
    }
  }
}

With the MCP configured, you can start talking. Tell Claude to begin the voice loop, enabling it to listen and respond in a continuous cycle.

Additional content

Security and setup notes: this flow relies on macOS’s native speech recognition and Python 3.10 or newer. Ensure you grant microphone access to the hear CLI when prompted and to Claude Code if required. The loop uses a self-prompting mechanism to keep itself alive, so you should have PyAutoGUI MCP installed for autonomous operation if you want fully hands-off behavior.

Notes on tools and capabilities

Voice Loop MCP exposes a small set of practical tools you’ll use during a session.

Troubleshooting and tips

If the loop stops, use the heartbeat tool to verify the loop is alive, and check the status with get_status(). Ensure microphone permissions are granted and that the hear CLI is functioning. If Claude isn’t responding, verify Python, Claude Code integration, and that the voice_loop_mcp module is importable by your Python environment.

Available tools

start_listening

Begin speech recognition to capture live audio input from your microphone.

stop_listening

Stop the active speech recognition session.

read_speech

Return the latest transcribed text from your speech input.

speak

Perform text-to-speech to deliver Claude's spoken response.

heartbeat

Send a keep-alive signal to maintain the self-prompting loop.

get_status

Query the current status of the Voice Loop MCP system.