MCP Listen

mcp-listen

Dale a tus agentes de IA la capacidad de escuchar

Captura de micrófono y herramientas de voz a texto para agentes compatibles con MCP.

Herramientas

Herramienta	Descripción
list_audio_devices	Lista los dispositivos de entrada de micrófono disponibles
capture_audio	Graba audio desde el micrófono y lo guarda como WAV
voice_query	Captura, transcribe en esta máquina (whisper.cpp) y consulta un modelo a través del daemon local de Ollama

Inicio rápido

Claude Code

claude mcp add mcp-listen npx mcp-listen

Claude Desktop / ChatGPT Desktop / Cursor / Windsurf / VS Code

Añade a tu configuración de MCP:

{
  "mcpServers": {
    "mcp-listen": {
      "command": "npx",
      "args": ["-y", "mcp-listen"]
    }
  }
}

Compatible con Claude Desktop, ChatGPT Desktop, Cursor, GitHub Copilot, Windsurf, VS Code, Gemini, Zed y cualquier cliente compatible con MCP.

Instalación global

npm install -g mcp-listen

Requisitos

Plataformas compatibles:

• Windows x64
• macOS Apple silicon (arm64)
• Linux x64 y arm64 (glibc)

Intel Mac (darwin-x64) no es compatible: Apple ha descontinuado la plataforma y no se publica ningún binario de decibri para ella.

Para list_audio_devices y capture_audio:

• Node.js 18+
• Un micrófono

Para voice_query (opcional):

• Ollama ejecutándose localmente
• Modelo Whisper GGML (consulta Configuración del modelo Whisper)

Referencia de herramientas

Los argumentos se validan antes de que se grabe o escriba nada. Un argumento que una herramienta no declara se rechaza con un error que lo nombra, en lugar de ignorarse silenciosamente. duration_ms debe ser un entero entre 100 y 30000; silence_ms un entero entre 100 y 10000; stop_on_silence un booleano; device un índice entero no negativo o un id de cadena no vacío de list_audio_devices. Un silence_ms que no puede tener efecto (pasado sin detección de silencio activa) se rechaza por la misma razón que los argumentos desconocidos. Una llamada rechazada no escribe nada en el disco.

list_audio_devices

Devuelve un array JSON de los dispositivos de entrada de audio disponibles.

Parámetros: Ninguno

Ejemplo de respuesta:

[
  { "index": 0, "name": "Microphone", "id": "wasapi:{0.0.1.00000000}.{00000000-0000-0000-0000-000000000001}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": true },
  { "index": 1, "name": "Microphone Array", "id": "wasapi:{0.0.1.00000000}.{00000000-0000-0000-0000-000000000002}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": false }
]

El id es estable entre reinicios y cambios de dispositivos. El index es posicional y puede cambiar cuando se añaden o eliminan dispositivos, y los nombres no son únicos. Prefiere id al seleccionar un dispositivo. En el raro caso de que el host no pueda producir un id estable para un dispositivo, su id es una cadena vacía y solo se puede seleccionar por index.

capture_audio

Graba audio desde el micrófono y lo guarda como archivo WAV. Graba durante exactamente duration_ms por defecto, o hasta que el hablante deje de hablar con stop_on_silence: true.

Parámetros:

Parámetro	Tipo	Predeterminado	Descripción
duration_ms	number	5000	Duración de la grabación en milisegundos (100-30000). Un máximo, no una duración exacta, cuando stop_on_silence es true
device	number o string	predeterminado del sistema	Índice del dispositivo o id estable del dispositivo de list_audio_devices
stop_on_silence	boolean	false	Detener cuando el hablante deje de hablar, detectado con detección de actividad de voz en el dispositivo (Silero VAD, incluido, sin descarga)
silence_ms	number	1000	Silencio continuo en milisegundos que finaliza una grabación con stop_on_silence (100-10000). Requiere stop_on_silence: true

Ejemplo de respuesta (duración fija):

{
  "path": "/tmp/mcp-listen-1712345678901.wav",
  "duration_ms": 5000,
  "sample_rate": 16000,
  "channels": 1,
  "size_bytes": 160044
}

Ejemplo de respuesta (stop_on_silence: true):

{
  "path": "/tmp/mcp-listen-1712345678901.wav",
  "duration_ms": 2600,
  "sample_rate": 16000,
  "channels": 1,
  "size_bytes": 83244,
  "stopped_by": "silence",
  "speech_detected": true
}

Con stop_on_silence, duration_ms en la respuesta es la duración real capturada, y stopped_by indica cómo terminó la grabación: "silence" (el hablante terminó), "ceiling" (se alcanzó el máximo de duration_ms) o "no_speech_timeout" (nadie habló durante 10 segundos; el WAV aún se devuelve, con speech_detected: false, por lo que el silencio es un resultado informado en lugar de un error). La detección se ejecuta por cada ~100ms de buffer de audio, por lo que el tiempo de espera efectivo se redondea al siguiente buffer, y la grabación conserva todo desde el inicio de la llamada hasta la decisión de detención: nada se filtra o recorta en los límites del habla, y el audio en sí es byte-idéntico a una captura de duración fija de los mismos sonidos.

voice_query

Pipeline de voz completo: captura audio, lo transcribe en esta máquina con whisper.cpp, envía la transcripción al daemon local de Ollama y devuelve la transcripción y la respuesta. El audio permanece en esta máquina. La grabación se detiene automáticamente cuando el hablante deja de hablar; pasa stop_on_silence: false para una grabación de duración fija.

Parámetros:

Parámetro	Tipo	Predeterminado	Descripción
duration_ms	number	15000 / 5000	Duración máxima de grabación en milisegundos (100-30000). Predeterminado 15000 mientras la detención por silencio está activa, 5000 con stop_on_silence: false
device	number o string	predeterminado del sistema	Índice del dispositivo o id estable del dispositivo de list_audio_devices
stop_on_silence	boolean	true	Detener la grabación cuando el hablante deje de hablar. Pasa false para grabar durante exactamente duration_ms
silence_ms	number	1000	Silencio continuo en milisegundos que finaliza la grabación (100-10000)
whisper_model	string	ggml-base.en.bin	Ruta o nombre de archivo del modelo Whisper GGML
language	string	en	Código de idioma para la transcripción
model	string	llama3.2	Nombre del modelo de Ollama
prompt	string	You are a helpful assistant.	Prompt del sistema para el LLM

Ejemplo de respuesta:

{
  "transcription": "What is the default port for PostgreSQL?",
  "response": "PostgreSQL runs on port 5432 by default.",
  "model": "llama3.2"
}

Resultados. voice_query informa cinco resultados distintos. Los campos estructurados son el contrato (isError, speech_detected, transcription); cualquier message es una pista legible por humanos cuyo texto no forma parte del contrato, por lo que un llamador se ramifica en los campos, nunca en la prosa. La regla es simple: si el pipeline se ejecutó, el resultado es un éxito (incluso cuando no encontró palabras); si una dependencia falló, el resultado es un error.

Resultado	isError	speech_detected	transcription	response
Normal	ausente	ausente	el texto	la respuesta
Sin habla en absoluto	ausente	false	null	null
Habla, pero sin palabras transcribibles	ausente	true (ausente con stop_on_silence: false)	null	null
Paso de transcripción fallido	true	ausente	ausente	ausente
Ollama no disponible, con error o vacío	true	ausente	ausente (el texto si la respuesta está vacía)	ausente (null si la respuesta está vacía)

Un llamador distingue "el usuario estuvo en silencio" de "el usuario habló pero no produjo palabras" por speech_detected (false vs true), ambos con transcription: null. El audio sin habla nunca llega al modelo de lenguaje: los marcadores de no-habla de whisper ([BLANK_AUDIO], [MUSIC], (silence) y similares) se tratan como sin palabras utilizables en lugar de enviarse como consulta.

Sin habla (speech_detected: false):

{
  "speech_detected": false,
  "stopped_by": "no_speech_timeout",
  "transcription": null,
  "response": null,
  "message": "No speech was detected. Ask the user to repeat, or check that the correct microphone is selected."
}

Habla, pero sin palabras transcribibles (speech_detected: true, transcription: null):

{
  "speech_detected": true,
  "stopped_by": "silence",
  "transcription": null,
  "response": null,
  "message": "Speech was detected but could not be transcribed. It may have been too quiet, too brief, or unclear. Ask the user to repeat, a little louder and closer to the microphone."
}

Las fallas de transcripción y dependencia devuelven isError: true con la causa real (un modelo faltante, una falla de carga de whisper, Ollama no ejecutándose, un tiempo de espera agotado o una respuesta vacía del modelo), para que un llamador que depura pueda distinguir si la falla fue en la captura, la transcripción o el modelo de lenguaje.

Cómo funciona

mcp-listen utiliza decibri para la captura de micrófono multiplataforma. Sin ffmpeg, sin SoX, sin herramientas de audio del sistema requeridas. Binarios nativos precompilados con configuración cero.

El audio se captura como PCM de 16 bits a 16kHz mono, el formato estándar para motores de voz a texto.

La detención por silencio utiliza el modelo de detección de actividad de voz Silero que viene dentro de decibri, ejecutándose en el dispositivo a través del ONNX Runtime incluido. No se descarga nada adicional y ningún audio sale de la máquina. La decisión de detención se mide en audio capturado, no en tiempo de reloj, y el VAD solo decide cuándo detener: nunca filtra ni altera las muestras grabadas.

La herramienta voice_query captura audio y lo transcribe en esta máquina con whisper.cpp, envía la transcripción al daemon local de Ollama y devuelve la transcripción y la respuesta al cliente llamador. El audio permanece en esta máquina.

Configuración del modelo Whisper

La herramienta voice_query requiere un archivo de modelo Whisper GGML. Descarga uno:

Linux / macOS:

mkdir -p ~/.mcp-listen/models
curl -L -o ~/.mcp-listen/models/ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin

Windows (PowerShell):

mkdir "$env:USERPROFILE\.mcp-listen\models" -Force
Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" -OutFile "$env:USERPROFILE\.mcp-listen\models\ggml-base.en.bin"

El modelo tiene ~150MB y se descarga una vez. También puedes establecer la variable de entorno WHISPER_MODEL_PATH a un directorio personalizado.

Configuración de Ollama

1. Instala Ollama desde https://ollama.com
2. Descarga un modelo: ollama pull llama3.2
3. Asegúrate de que Ollama esté ejecutándose: ollama serve

Limitaciones conocidas

1. Un transitorio fuerte puede registrarse como habla. La detención por silencio decide que "el habla ha comenzado" a partir de la puntuación del VAD, por lo que un portazo o una tos pueden iniciar la cuenta regresiva y terminar la grabación después de silence_ms de silencio, produciendo una captura corta de mayormente silencio. El resultado es visible, no silencioso: el resultado informa la duración real, y voice_query informa una transcripción vacía en lugar de inventar una. Un guardia de duración mínima de habla es un refinamiento candidato.
2. voice_query requiere Ollama ejecutándose. Si Ollama no está ejecutándose, la herramienta devuelve un mensaje de error claro.
3. El modelo Whisper debe descargarse antes del primer uso. voice_query no descarga el modelo por sí mismo; la primera llamada requiere un modelo pre-descargado (~150MB). Consulta Configuración del modelo Whisper.
4. Sin transmisión. El patrón de solicitud/respuesta de MCP significa que toda la grabación se captura, luego se transcribe y luego se envía al LLM. Sin resultados parciales en tiempo real.
5. Archivos temporales. capture_audio escribe archivos WAV en el directorio temporal del sistema y devuelve la ruta, por lo que el archivo debe sobrevivir a la llamada para que el llamador pueda leerlo. Las grabaciones de más de 24 horas se eliminan la próxima vez que se inicie el servidor; las grabaciones realizadas desde el último reinicio persisten hasta entonces. voice_query elimina su grabación tan pronto como se completa la consulta.

Solución de problemas

Windows: "Error opening microphone" Windows puede bloquear el acceso al micrófono por defecto. Ve a Configuración > Privacidad y seguridad > Micrófono y asegúrate de que el acceso al micrófono esté habilitado para aplicaciones de escritorio.

Ollama: "Ollama is not running" Algunas instalaciones de Ollama se inician como un servicio en segundo plano automáticamente. Si ves este error, ejecuta ollama serve manualmente o verifica que el servicio de Ollama esté ejecutándose.

Whisper: "model not found" El archivo del modelo whisper debe descargarse antes del primer uso. Consulta Configuración del modelo Whisper para instrucciones.

Whisper: "installed but failed to load" El paquete @kutalia/whisper-node-addon está presente pero falta una biblioteca nativa de la que depende o es incompatible en tu sistema. El error incluye el mensaje subyacente del cargador que nombra la biblioteca. Reinstalar el paquete no ayudará; resuelve la biblioteca nombrada en su lugar.

Licencia

Apache-2.0. Consulta LICENSE para detalles.

Copyright 2026 Decibri