MCP Listen

mcp-listen

Dê aos seus agentes de IA a capacidade de ouvir

Captura de microfone e ferramentas de fala para texto para agentes compatíveis com MCP.

Ferramentas

Ferramenta	Descrição
list_audio_devices	Lista os dispositivos de entrada de microfone disponíveis
capture_audio	Grava áudio do microfone e salva como WAV
voice_query	Captura, transcreve nesta máquina (whisper.cpp) e consulta um modelo através do daemon local Ollama

Início Rápido

Claude Code

claude mcp add mcp-listen npx mcp-listen

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

Adicione à sua configuração MCP:

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

Compatível com Claude Desktop, ChatGPT Desktop, Cursor, GitHub Copilot, Windsurf, VS Code, Gemini, Zed e qualquer cliente compatível com MCP.

Instalação Global

npm install -g mcp-listen

Requisitos

Plataformas suportadas:

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

Intel Mac (darwin-x64) não é suportado: a Apple descontinuou a plataforma e nenhum binário decibri é publicado para ela.

Para list_audio_devices e capture_audio:

• Node.js 18+
• Um microfone

Para voice_query (opcional):

• Ollama rodando localmente
• Modelo Whisper GGML (veja Configuração do Modelo Whisper)

Referência das Ferramentas

Os argumentos são validados antes que qualquer coisa seja gravada ou escrita. Um argumento que uma ferramenta não declara é rejeitado com um erro que o nomeia, em vez de ser silenciosamente ignorado. duration_ms deve ser um inteiro entre 100 e 30000; silence_ms um inteiro entre 100 e 10000; stop_on_silence um booleano; device um índice inteiro não negativo ou um id de string não vazio de list_audio_devices. Um silence_ms que não pode ter efeito (passado sem detecção de silêncio ativa) é rejeitado pela mesma razão que argumentos desconhecidos. Uma chamada rejeitada não escreve nada no disco.

list_audio_devices

Retorna um array JSON dos dispositivos de entrada de áudio disponíveis.

Parâmetros: Nenhum

Exemplo de resposta:

[
  { "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 }
]

O id é estável entre reinicializações e mudanças de dispositivos. O index é posicional e pode mudar quando dispositivos são adicionados ou removidos, e os nomes não são únicos. Prefira id ao selecionar um dispositivo. No raro caso em que o host não consegue produzir um id estável para um dispositivo, seu id é uma string vazia e ele só pode ser selecionado por index.

capture_audio

Grava áudio do microfone e salva como um arquivo WAV. Grava por exatamente duration_ms por padrão, ou até o falante parar de falar com stop_on_silence: true.

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
duration_ms	número	5000	Duração da gravação em milissegundos (100-30000). Um máximo, não um comprimento exato, quando stop_on_silence é verdadeiro
device	número ou string	padrão do sistema	Índice do dispositivo ou id estável do dispositivo de list_audio_devices
stop_on_silence	booleano	falso	Para quando o falante parar de falar, detectado com detecção de atividade de voz no dispositivo (Silero VAD, incluído, sem download)
silence_ms	número	1000	Silêncio contínuo em milissegundos que encerra uma gravação stop_on_silence (100-10000). Requer stop_on_silence: true

Exemplo de resposta (duração fixa):

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

Exemplo de resposta (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
}

Com stop_on_silence, duration_ms na resposta é o comprimento real capturado, e stopped_by diz como a gravação terminou: "silence" (o falante terminou), "ceiling" (o máximo de duration_ms foi atingido), ou "no_speech_timeout" (ninguém falou por 10 segundos; o WAV ainda é retornado, com speech_detected: false, então o silêncio é um resultado relatado em vez de um erro). A detecção roda a cada ~100ms de buffer de áudio, então o tempo de espera efetivo é arredondado para o próximo buffer, e a gravação mantém tudo desde o início da chamada até a decisão de parar: nada é bloqueado ou cortado nas fronteiras da fala, e o áudio em si é byte-idêntico a uma captura de duração fixa dos mesmos sons.

voice_query

Pipeline de voz completo: captura áudio, transcreve nesta máquina com whisper.cpp, envia a transcrição para o daemon local Ollama, e retorna a transcrição e a resposta. O áudio permanece nesta máquina. A gravação para automaticamente quando o falante para de falar; passe stop_on_silence: false para uma gravação de comprimento fixo.

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
duration_ms	número	15000 / 5000	Duração máxima da gravação em milissegundos (100-30000). Padrão 15000 enquanto a detecção de silêncio está ativa, 5000 com stop_on_silence: false
device	número ou string	padrão do sistema	Índice do dispositivo ou id estável do dispositivo de list_audio_devices
stop_on_silence	booleano	verdadeiro	Para a gravação quando o falante parar de falar. Passe falso para gravar por exatamente duration_ms
silence_ms	número	1000	Silêncio contínuo em milissegundos que encerra a gravação (100-10000)
whisper_model	string	ggml-base.en.bin	Caminho ou nome do arquivo do modelo Whisper GGML
language	string	en	Código de idioma para transcrição
model	string	llama3.2	Nome do modelo Ollama
prompt	string	Você é um assistente útil.	Prompt do sistema para o LLM

Exemplo de resposta:

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

Resultados. voice_query relata cinco resultados distintos. Os campos estruturados são o contrato (isError, speech_detected, transcription); qualquer message é uma dica legível por humanos cujo texto não faz parte do contrato, então um chamador ramifica nos campos, nunca na prosa. A regra é simples: se o pipeline rodou, o resultado é um sucesso (mesmo quando não encontrou palavras); se uma dependência quebrou, o resultado é um erro.

Resultado	isError	speech_detected	transcription	response
Normal	ausente	ausente	o texto	a resposta
Nenhuma fala	ausente	false	null	null
Fala, mas sem palavras transcrevíveis	ausente	true (ausente com stop_on_silence: false)	null	null
Etapa de transcrição falhou	true	ausente	ausente	ausente
Ollama indisponível, com erro ou vazio	true	ausente	ausente (o texto se a resposta estiver vazia)	ausente (null se a resposta estiver vazia)

Um chamador distingue "o usuário ficou em silêncio" de "o usuário falou mas não produziu palavras" por speech_detected (false vs true), ambos carregando transcription: null. Áudio sem fala nunca chega ao modelo de linguagem: os marcadores de não-fala do whisper ([BLANK_AUDIO], [MUSIC], (silence) e similares) são tratados como nenhuma palavra utilizável em vez de serem enviados como consulta.

Nenhuma fala (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."
}

Fala, mas sem palavras transcrevíveis (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."
}

Falhas de transcrição e dependência retornam isError: true com a causa real (um modelo ausente, uma falha de carregamento do whisper, Ollama não rodando, um timeout ou uma resposta vazia do modelo), então um chamador depurando pode dizer se a falha foi na captura, na transcrição ou no modelo de linguagem.

Como Funciona

mcp-listen usa decibri para captura de microfone multiplataforma. Sem ffmpeg, sem SoX, sem ferramentas de áudio do sistema necessárias. Binários nativos pré-compilados com zero configuração.

O áudio é capturado como PCM de 16 bits a 16kHz mono, o formato padrão para mecanismos de fala para texto.

A detecção de silêncio usa o modelo de detecção de atividade de voz Silero que vem dentro do decibri, rodando no dispositivo através do ONNX Runtime incluído. Nada extra é baixado e nenhum áudio sai da máquina. A decisão de parar é medida no áudio capturado, não no tempo de relógio, e o VAD só decide quando parar: ele nunca bloqueia ou altera as amostras gravadas.

A ferramenta voice_query captura áudio e transcreve nesta máquina com whisper.cpp, envia a transcrição para o daemon local Ollama e retorna a transcrição e a resposta ao cliente chamador. O áudio permanece nesta máquina.

Configuração do Modelo Whisper

A ferramenta voice_query requer um arquivo de modelo Whisper GGML. Baixe um:

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"

O modelo tem ~150MB e é baixado uma vez. Você também pode definir a variável de ambiente WHISPER_MODEL_PATH para um diretório personalizado.

Configuração do Ollama

1. Instale o Ollama de https://ollama.com
2. Puxe um modelo: ollama pull llama3.2
3. Garanta que o Ollama esteja rodando: ollama serve

Limitações Conhecidas

1. Um transiente alto pode ser registrado como fala. A detecção de silêncio decide que "a fala começou" a partir da pontuação do VAD, então uma batida de porta ou uma tosse pode iniciar a contagem regressiva e encerrar a gravação após silence_ms de silêncio, produzindo uma captura curta de principalmente silêncio. O resultado é visível, não silencioso: o resultado relata a duração real, e voice_query relata uma transcrição vazia em vez de inventar uma. Uma proteção de duração mínima de fala é um refinamento candidato.
2. voice_query requer Ollama rodando. Se o Ollama não estiver rodando, a ferramenta retorna uma mensagem de erro clara.
3. O modelo Whisper deve ser baixado antes do primeiro uso. voice_query não baixa o modelo em si; a primeira chamada requer um modelo pré-baixado (~150MB). Veja Configuração do Modelo Whisper.
4. Sem streaming. O padrão de requisição/resposta do MCP significa que toda a gravação é capturada, depois transcrita, depois enviada ao LLM. Sem resultados parciais em tempo real.
5. Arquivos temporários. capture_audio escreve arquivos WAV no diretório temporário do sistema e retorna o caminho, então o arquivo precisa sobreviver à chamada para o chamador lê-lo. Gravações com mais de 24 horas são removidas na próxima vez que o servidor iniciar; gravações feitas desde o último reinício persistem até então. voice_query exclui sua gravação assim que a consulta é concluída.

Solução de Problemas

Windows: "Erro ao abrir o microfone" O Windows pode bloquear o acesso ao microfone por padrão. Vá para Configurações > Privacidade e segurança > Microfone e garanta que o acesso ao microfone esteja habilitado para aplicativos de desktop.

Ollama: "Ollama não está rodando" Algumas instalações do Ollama iniciam como um serviço em segundo plano automaticamente. Se você vir este erro, execute ollama serve manualmente ou verifique se o serviço Ollama está rodando.

Whisper: "modelo não encontrado" O arquivo do modelo whisper deve ser baixado antes do primeiro uso. Veja Configuração do Modelo Whisper para instruções.

Whisper: "instalado, mas falhou ao carregar" O pacote @kutalia/whisper-node-addon está presente, mas uma biblioteca nativa da qual ele depende está ausente ou é incompatível no seu sistema. O erro inclui a mensagem subjacente do carregador nomeando a biblioteca. Reinstalar o pacote não ajudará; resolva a biblioteca nomeada em vez disso.

Licença

Apache-2.0. Veja LICENÇA para detalhes.

Copyright 2026 Decibri