Skip to main content
Glama

livechat-mcp

Un servidor de Model Context Protocol (MCP) que te permite mantener una conversación de voz continua con tu asistente de programación de IA. Tú hablas, tu voz se transcribe localmente con Whisper y cada enunciado se entrega al asistente como si lo hubieras escrito. Sin cambiar de pestaña, sin copiar/pegar, sin grabaciones por lotes.

Funciona con cualquier host MCP. Soporte de primera clase para:

  • Claude Code

  • Codex CLI

  • Gemini CLI

Requisitos

  • macOS, Linux o Windows (nativo mediante PowerShell, o bajo WSL2 / Git Bash).

  • Python 3.10+

  • Un host MCP instalado (Claude Code, Codex, Gemini, etc.)

  • Un micrófono funcional

  • ~500 MB de disco para la caché del modelo Whisper + dependencias

  • uv para la gestión del proyecto (recomendado)

Related MCP server: Voice MCP

Instalación rápida (recomendada)

Desde un clon del repositorio:

# macOS / Linux / Git Bash on Windows
./install.sh
# Native Windows PowerShell
.\install.ps1

El bootstrap detecta el sistema operativo, instala portaudio si es necesario (brew / apt / dnf / pacman / zypper — los wheels de Windows lo incluyen integrado), instala uv si falta, ejecuta uv sync, coloca el asistente en ~/.local/bin y lanza el asistente de configuración interactivo.

Windows: el bloqueo nativo utiliza msvcrt y la señalización de toma de control se basa en archivos, por lo que no hay dependencia de fcntl. El asistente interactivo es un script de bash — install.ps1 lo invoca a través de Git Bash, el cual ofrece instalar mediante winget si falta.

Configuración manual

Si prefieres instalar paso a paso, esto es lo que hace install.sh:

1. Instalar portaudio

sounddevice necesita portaudio.

  • macOS: brew install portaudio

  • Debian/Ubuntu: sudo apt-get install libportaudio2 portaudio19-dev

  • Fedora/RHEL: sudo dnf install portaudio portaudio-devel

  • Arch: sudo pacman -S portaudio

2. Instalar uv si no lo tienes

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

3. Clonar e instalar dependencias

cd livechat-mcp
uv sync

Esto creará .venv/ e instalará mcp, faster-whisper, sounddevice, silero-vad, torch, etc.

4. Ejecutar el asistente de configuración

install -m 0755 bin/livechat-mcp ~/.local/bin/livechat-mcp
livechat-mcp setup

El asistente:

  1. Preguntará para qué asistentes instalar (Claude Code / Codex / Gemini, cualquier combinación).

  2. Copiará los comandos slash /livechat y /endlivechat a los hosts que admitan comandos slash personalizados. Para Codex, instala tanto archivos de prompt heredados como una skill livechat, ya que las versiones actuales de Codex CLI no exponen prompts personalizados como /livechat.

  3. Registrará el servidor MCP en el archivo de configuración de cada host.

  4. Te guiará a través de las variables de entorno ajustables (umbral de silencio, modelo Whisper, etc.) — presiona Enter para mantener los valores predeterminados.

Asegúrate de que ~/.local/bin esté en tu PATH (ya lo está si usaste el instalador oficial de uv).

Si prefieres configurar las cosas manualmente, los pasos para cada host se encuentran a continuación.

5. Conceder permiso de micrófono

  • macOS: la primera vez que el servidor intente capturar audio, macOS le pedirá a tu aplicación de terminal (Terminal, iTerm, Ghostty, Warp, etc.) acceso al micrófono. Si pierdes el aviso, habilítalo manualmente:

    Ajustes del Sistema → Privacidad y seguridad → Micrófono → habilitar para tu terminal

    Si omites esto, la captura de audio devolverá silencio silenciosamente y nada se transcribirá.

  • Windows: Configuración → Privacidad y seguridad → Micrófono → permitir que las aplicaciones de escritorio accedan al micrófono (y asegúrate de que tu terminal tenga permiso).

  • Linux: normalmente no hay aviso — solo asegúrate de que tu usuario tenga el acceso correcto a ALSA / PulseAudio / Pipewire (normalmente el grupo audio).

6. Pre-descargar el modelo Whisper (opcional)

La primera ejecución descarga base.en (~150 MB). Puedes pre-cargarlo:

uv run python -c "from faster_whisper import WhisperModel; WhisperModel('base.en', device='cpu', compute_type='int8')"

Instalación manual (omite si usaste livechat-mcp setup)

Claude Code

Copia los comandos slash:

mkdir -p ~/.claude/commands
cp commands/livechat.md ~/.claude/commands/
cp commands/endlivechat.md ~/.claude/commands/

Registra el servidor MCP:

claude mcp add livechat -- uv --directory "$(pwd)" run livechat-mcp

O edita ~/.claude.json directamente:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Codex CLI

Instala la skill de Codex y los archivos de prompt heredados:

mkdir -p ~/.codex/skills/livechat
cp skills/livechat/SKILL.md ~/.codex/skills/livechat/
mkdir -p ~/.codex/prompts
cp commands/livechat.md ~/.codex/prompts/
cp commands/endlivechat.md ~/.codex/prompts/

Registra el servidor MCP en ~/.codex/config.toml:

[mcp_servers.livechat]
command = "uv"
args = ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]

Gemini CLI

Gemini usa TOML para comandos personalizados. El asistente los genera por ti; para hacerlo a mano, consulta commands/gemini/livechat.toml.template (creado al ejecutar livechat-mcp setup una vez).

Registra el servidor MCP en ~/.gemini/settings.json:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Uso

Abre la CLI de tu asistente en cualquier terminal:

claude    # or: codex    or: gemini

Luego, en el prompt del asistente:

/livechat            # Claude Code, Gemini CLI
use livechat         # Codex CLI

Se requiere reiniciar Codex. Codex solo carga skills y servidores MCP al inicio. Si ejecutaste el asistente mientras Codex estaba abierto, ciérralo y reinícialo antes de usar use livechat.

Codex 0.128.0 no admite comandos slash /livechat definidos por el usuario; / está actualmente reservado para los comandos integrados de Codex. La configuración instala una skill livechat descubrible en su lugar, por lo que puedes escribir use livechat o abrir /skills y seleccionar livechat.

El asistente llamará a get_voice_input y comenzará a escuchar. Habla normalmente. Cuando haces una pausa de ~1.5 segundos, tu enunciado se finaliza, se transcribe y se envía como un prompt. El asistente responde y luego escucha inmediatamente el siguiente enunciado.

Mientras el asistente genera una respuesta, el micrófono sigue activo — cualquier cosa que digas durante ese tiempo se pone en cola y se entrega todo a la vez en la siguiente llamada a get_voice_input.

Finalizar una sesión

Tres formas:

  1. /endlivechat — la más limpia, se ejecuta desde el prompt del asistente. (Primero deberás interrumpir el turno actual si está a mitad de respuesta).

  2. Frase de activación — di terminate voice session now. La transcripción activa el apagado. La frase es intencionalmente incómoda para evitar colisiones con contenido de revisión real. Configurable mediante LIVECHAT_END_PHRASE.

  3. Ctrl+C — mata el servidor MCP. El asistente verá un error de herramienta en la siguiente llamada y detendrá el bucle.

Configuración

Todos los parámetros ajustables residen en livechat_mcp/config.py y pueden ser sobrescritos mediante variables de entorno:

Var

Predeterminado

Notas

LIVECHAT_WHISPER_MODEL

base.en

Solo inglés: tiny.en, base.en, small.en, medium.en. Multilingüe (quita .en): tiny, base, small, medium

LIVECHAT_WHISPER_LANGUAGE

en

Código de idioma (en, pt, es, …) o auto para detectar por enunciado. auto requiere un modelo multilingüe

LIVECHAT_WHISPER_DEVICE

auto

cpu, cuda, auto

LIVECHAT_WHISPER_COMPUTE

int8

int8 (CPU), float16 (GPU)

LIVECHAT_SILENCE_SEC

1.5

Silencio después del habla para finalizar un enunciado

LIVECHAT_VAD_THRESHOLD

0.5

Umbral de probabilidad de habla de Silero VAD

LIVECHAT_MIN_UTTERANCE_SEC

0.4

Longitud mínima del enunciado (filtra toses)

LIVECHAT_MAX_UTTERANCE_SEC

120

Corte forzado de enunciados descontrolados

LIVECHAT_LONG_POLL_SEC

300

Cuánto tiempo bloquea get_voice_input antes de __NO_INPUT__

LIVECHAT_END_PHRASE

terminate voice session now

Frase hablada para finalizar la sesión

LIVECHAT_DEBUG

sin establecer

Establecer en 1 para registros de depuración de VAD/segmentación en stderr

La forma fácil de establecer esto es livechat-mcp set CLAVE VALOR — edita el bloque env en cada configuración de host que encuentra (Claude / Codex / Gemini).

livechat-mcp show           # print current env block(s)
livechat-mcp set LIVECHAT_SILENCE_SEC 1.5
livechat-mcp unset LIVECHAT_DEBUG

Reinicia la CLI de tu asistente después de cualquier cambio — las variables de entorno MCP son leídas por el servidor al inicio.

Para hacerlo manualmente, edita el campo env de la entrada MCP de livechat en la configuración de cada host. Ejemplo para Claude Code:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/abs/path", "run", "livechat-mcp"],
      "env": {
        "LIVECHAT_WHISPER_MODEL": "small.en",
        "LIVECHAT_DEBUG": "1"
      }
    }
  }
}

Solución de problemas

No sucede nada cuando hablo. Verifica (en orden): permiso de micrófono para tu aplicación de terminal, nivel de entrada de micrófono (Ajustes del Sistema → Sonido), establece LIVECHAT_DEBUG=1 y observa stderr para eventos VAD, reduce LIVECHAT_VAD_THRESHOLD a 0.3.

Las transcripciones son inexactas. Actualiza el modelo: LIVECHAT_WHISPER_MODEL=small.en o medium.en. medium.en es notablemente más lento en CPU (aunque sigue siendo casi en tiempo real) pero mucho mejor para vocabulario técnico.

El enunciado termina demasiado rápido / demasiado lento. Ajusta LIVECHAT_SILENCE_SEC (o ejecuta livechat-mcp set LIVECHAT_SILENCE_SEC 1.5). 1.0–4.5 es el rango útil — un valor más bajo se siente más ágil pero corre el riesgo de cortar pausas a mitad de pensamiento.

uv no encontrado. Instala uv (recomendado) o cambia el command de la configuración MCP a una invocación directa de python -m livechat_mcp.server desde dentro de un venv activado.

El servidor inicia pero el asistente nunca llama a la herramienta. Asegúrate de que se invocó /livechat. Sin el comando slash, el asistente no tiene instrucciones para entrar en el bucle.

Los registros del servidor van a la interfaz del asistente como basura / rompen el protocolo. Esto no debería suceder — todo el registro del servidor va a stderr. Si lo ves, informa de un error. Asegúrate de no haber añadido ninguna declaración print(...) sin file=sys.stderr.

Errores de portaudio al iniciar. Instálalo: brew install portaudio. Si está instalado y sigue fallando, intenta brew reinstall portaudio y reinstala sounddevice: uv sync --reinstall.

Cómo funciona (versión corta)

[mic] → [Silero VAD] → [Whisper] → [queue] ← [get_voice_input tool] ← [Assistant]
   ↑________background thread, always running________↑

La tubería de audio está desacoplada de la herramienta MCP, por lo que el micrófono está siempre activo mientras el servidor está encendido. Los enunciados hablados mientras el asistente genera una respuesta se ponen en cola y se entregan en la siguiente llamada a la herramienta.

Licencia

MIT.

Available Tools

4 tools
end_voice_sessionA

Cleanly end the current voice session. After calling this, any further get_voice_input calls will return 'END_SESSION'. Use this when the user invokes /endlivechat or otherwise asks to stop voice mode.

Inputs: no named parameters.

get_voice_inputA

Returns the next voice utterance from the user as text. Used in a loop during voice review sessions. If multiple utterances are queued, they are joined with ' / '. Returns the literal string 'END_SESSION' when the user has ended the session (Ctrl+C, /endlivechat, or wake phrase) — stop calling this tool when you see that. Returns 'NO_INPUT' if the long-poll timed out with no speech; in that case, call this tool again. Returns 'ALREADY_RUNNING:' if another livechat MCP process (e.g. another Claude Code window) currently holds the session lock — ask the user to confirm a takeover, then call take_over_voice_session if they agree.

Inputs: no named parameters.

reset_voice_sessionA

Clear stale shutdown state from a previous /endlivechat in this same MCP server process so a new voice session can start cleanly. Call this once at the very beginning of a /livechat session, after the announcement and before the first get_voice_input. Safe to call mid-session: if a session is already running healthily this is a no-op and no in-flight utterances are dropped.

Inputs: no named parameters.

take_over_voice_sessionA

Forcibly take the cross-process session lock from another livechat MCP instance. Signals the holder to release, waits briefly, and starts a new session here. Only call this after the user explicitly confirms taking over from the other window. Returns 'OK' on success or an error string on failure.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: retrieving input, ending the session, taking over a lock, and resetting state. No overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., get_voice_input, end_voice_session). The pattern is uniform and predictable.

    Tool Count5/5

    Four tools is well-scoped for a voice session lifecycle. Each tool serves a necessary function with no redundancy, fitting the server's narrow purpose.

    Completeness5/5

    The tool surface covers the full voice session lifecycle: starting clean, retrieving input, ending, and handling cross-process takeover. No obvious dead ends or missing operations for the intended use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to speak aloud using text-to-speech functionality. Works with agents running inside devcontainers and provides configurable voice settings for creating chatty AI companions.
      6
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural voice interaction with Claude Code through speech-to-text, supporting wake word activation and multiple backends like Whisper and Google. It allows users to execute commands and control their coding environment hands-free via their microphone.
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      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.
      16
      Apache 2.0