whisper-windows-mcp

Transcrição de áudio/vídeo acelerada por GPU local para o Claude Desktop no Windows, usando whisper.cpp com suporte a AMD Vulkan, processamento em lote em segundo plano e geração de legendas.

Documentação

whisper-windows-mcp

CI

whisper-windows-mcp MCP server

Um servidor MCP (Model Context Protocol) nativo para Windows que permite ao Claude Desktop transcrever arquivos de áudio e vídeo localmente usando whisper.cpp — com aceleração de GPU, suporte multilíngue e processamento em lote. Toda a transcrição é executada localmente — nenhum áudio, vídeo ou caminho de arquivo sai da sua máquina.

Por que isso existe? O pacote whisper-mcp popular foi criado para macOS e assume um ambiente Unix. Ele não funciona no Windows. Este pacote foi escrito especificamente para usuários de Windows que desejam transcrição de IA local integrada ao Claude Desktop.


O que você pode fazer com ele

Após a instalação, você pode dizer coisas como estas diretamente no Claude Desktop:

  • "Transcreva C:\Users\Me\Downloads\meeting.mp3"
  • "Transcreva esta pasta de gravações e salve cada uma como arquivo de texto"
  • "Gere legendas em japonês e inglês para este vídeo"
  • "Inicie uma transcrição em lote de tudo nesta pasta"
  • "Quanto tempo levará para transcrever estes arquivos?"
  • "Verifique se a aceleração de GPU está funcionando"
  • "Transcreva este arquivo em modo privado"

Requisitos

  1. Node.js 18 ou superiornodejs.org
  2. Binários whisper.cpp com suporte a GPU Vulkan — veja o Passo 1
  3. Um arquivo de modelo Whisper — veja o Passo 2
  4. FFmpeg — necessário para arquivos de vídeo e áudio que não sejam WAV/MP3

Passo 1 — Instalar os binários whisper.cpp

Opção A — Versão Vulkan pré-compilada (recomendada)

Baixe whisper-vulkan-win-x64.zip da página de versões.

Esta é uma compilação personalizada com aceleração de GPU Vulkan habilitada. Funciona com GPUs AMD, NVIDIA e Intel — sem necessidade de SDK específico do fabricante.

Extraia para C:\whisper\Release\. Você deve terminar com:

C:\whisper\Release\whisper-cli.exe
C:\whisper\Release\ggml-vulkan.dll
C:\whisper\Release\ggml.dll
C:\whisper\Release\ggml-base.dll
C:\whisper\Release\ggml-cpu.dll
C:\whisper\Release\whisper.dll

A aceleração de GPU é automática — nenhuma configuração adicional é necessária.

Opção B — Compilar a partir do código-fonte

Requer: Git, CMake, Visual Studio Build Tools 2022+ com "Desenvolvimento para desktop com C++", SDK Vulkan do lunarg.com.

git clone https://github.com/ggml-org/whisper.cpp
cd whisper.cpp
cmake -B build -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --target whisper-cli

Copie os binários de build\bin\Release\ para C:\whisper\Release\.

Nota: As versões oficiais do whisper.cpp para Windows no GitHub não incluem uma compilação Vulkan. Você deve usar a versão pré-compilada acima ou compilar a partir do código-fonte com -DGGML_VULKAN=ON.


Passo 2 — Baixar um modelo Whisper

ModeloTamanhoVelocidadePrecisãoMelhor para
ggml-tiny.en.bin75 MBMuito rápidoBásicaTestes rápidos
ggml-base.en.bin142 MBRápidoBoaInglês do dia a dia
ggml-small.en.bin466 MBModeradoMelhorGravações importantes
ggml-medium.en.bin1,5 GBRápido na GPUMuito boaMelhor qualidade em inglês
ggml-large-v3-turbo.bin1,6 GBRápido na GPUExcelenteRecomendado para trabalho em lote em inglês com GPU — ~6x mais rápido que large-v3 com perda mínima de precisão
ggml-large-v3.bin2,9 GBRápido na GPUExcelenteMultilíngue, precisão máxima
ggml-medium.en-q5_0.bin514 MBRápidoMuito boaMelhor opção em inglês apenas com CPU — alta precisão com baixo uso de memória
ggml-large-v3-turbo-q5_0.bin547 MBRápidoExcelenteMelhor opção multilíngue apenas com CPU
ggml-large-v3-q5_0.bin1,1 GBModerado na CPUExcelenteMultilíngue, amigável para CPU

Use download_model no Claude Desktop para instalar qualquer um deles diretamente. Para uso somente em inglês: large-v3-turbo (GPU) ou medium.en-q5_0 (CPU) são os melhores pontos de partida. Para uso multilíngue: large-v3-turbo ou large-v3-turbo-q5_0 (CPU). Modelos somente em inglês (*.en.bin) produzem [FOREIGN] em áudio não-inglês e não podem ser usados para outros idiomas.


Passo 3 — Instalar o FFmpeg

O FFmpeg é necessário para arquivos de vídeo e formatos de áudio não nativos.

Instale via winget:

winget install ffmpeg

Ou baixe de ffmpeg.org e adicione ao seu PATH.

Verifique:

ffmpeg -version

Passo 4 — Instalar este servidor MCP

npm install -g whisper-windows-mcp

Passo 5 — Configurar o Claude Desktop

Abra o Claude Desktop → Configurações → Desenvolvedor → Editar Config.

Adicione a entrada whisper:

{
  "mcpServers": {
    "whisper": {
      "command": "npx",
      "args": ["-y", "whisper-windows-mcp"],
      "env": {
        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin"
      }
    }
  }
}

Localização do arquivo de configuração: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Use barras invertidas duplas em todos os caminhos.

Salve e reinicie completamente o Claude Desktop. Você deve ver whisper listado com um selo verde de execução em Configurações → Desenvolvedor.


Passo 6 — Verificar sua configuração

No Claude Desktop, pergunte:

"Verifique sua configuração do whisper"

Depois:

"Verifique seu hardware do sistema"

Isso confirma que sua GPU foi detectada e que a aceleração Vulkan está ativa.


Ferramentas disponíveis

transcribe_audio

Transcreve um único arquivo. Suporta modo bloqueante (padrão) ou modo em segundo plano para arquivos longos.

ParâmetroDescrição
file_pathCaminho absoluto para o arquivo (obrigatório)
languageCódigo do idioma (en, ja, es, etc.) ou auto para detectar. Padrão: en
output_formattimestamps (padrão), text, json, srt, vtt, lrc ou csv
save_to_fileSalva a transcrição como .txt ao lado do arquivo de origem
backgroundExecuta como tarefa em segundo plano — retorna um ID de tarefa imediatamente. Use check_progress para monitorar. Recomendado para arquivos com mais de 10 minutos.
privacy_modeSubstitui o modo privado para esta chamada. true = apenas metadados, sem transmissão do texto da transcrição. false = retorna o texto mesmo se WHISPER_PRIVACY_MODE=true globalmente. Omita para usar a configuração global.
threadsSubstituição de threads da CPU
temperatureTemperatura de amostragem 0,0–1,0. Padrão 0,0 (determinístico).
promptString de contexto prévio — melhora a precisão para vocabulário específico de domínio ou nomes de falantes. Exemplo: "Names: Keemstar, DramaAlert."
condition_on_prev_textReativa o condicionamento de contexto entre segmentos. Padrão falso.
beam_sizeLargura da busca em feixe. Maior = mais preciso, mais lento. Padrão 5.
best_ofSequências candidatas avaliadas. Padrão 5.
gpu_deviceÍndice do dispositivo GPU para sistemas multi-GPU. Padrão 0.
processorsContagem de processadores paralelos. Padrão 1.
word_timestampsUma palavra por segmento com timestamp. Útil para alinhamento de clipes.
max_segment_lengthComprimento máximo do segmento em caracteres.
diarizeDiarização de falantes estéreo — requer áudio estéreo com falantes em canais separados.
tinydiarizeDetecção de turno de fala mono — marca [SPEAKER_TURN] em mudanças de falante em áudio de canal único. Requer um modelo tdrz: download_model small.en-tdrz, depois switch_model ggml-small.en-tdrz.bin.
vad_modelCaminho para o modelo VAD Silero .bin. Remove silêncios antes da transcrição — reduz alucinações em arquivos ruidosos.
offset_tDeslocamento inicial em milissegundos.
durationDuração do processamento em milissegundos a partir do deslocamento.

Formatos de saída:

  • timestamps — segmentos com timestamp, ex.: [00:00:01.230 --> 00:00:04.560] Hello world (padrão)
  • text — texto simples, sem códigos de tempo
  • json — JSON estruturado (somente modo bloqueante)
  • srt — arquivo de legenda SubRip salvo ao lado da origem
  • vtt — arquivo de legenda WebVTT salvo ao lado da origem
  • lrc — formato LRC de letras/karaokê salvo ao lado da origem
  • csv — CSV com timestamps salvo ao lado da origem

check_progress

Monitora uma tarefa de transcrição em segundo plano iniciada com transcribe_audio (background=true).

Retorna o tempo decorrido, o último timestamp processado e a transcrição completa quando concluída.

ParâmetroDescrição
job_idID da tarefa retornado por transcribe_audio
privacy_modeSubstitui o modo privado para esta verificação. true = apenas metadados, independentemente de como a tarefa foi iniciada.

start_batch

Transcrição em lote sequencial automatizada de todos os arquivos não transcritos em uma pasta. Ordena por duração (mais curtos primeiro), processa um por vez como tarefas em segundo plano e valida cada saída. O lote avança automaticamente quando cada arquivo termina — sem necessidade de polling.

ParâmetroDescrição
folder_pathCaminho para a pasta (obrigatório)
languageCódigo do idioma. Padrão: en
threadsSubstituição de threads da CPU
output_formattimestamps (padrão) ou text
privacy_modeSubstitui o modo privado. Uma confirmação é necessária antes do início do lote; todos os arquivos são então processados sem supervisão. Nenhum texto de transcrição é retornado.

check_batch_progress

Monitora um lote em execução. Avança automaticamente para o próximo arquivo quando o atual termina. Retorna o progresso geral, o arquivo atual com timestamp e quaisquer arquivos com falha.

ParâmetroDescrição
batch_idID do lote retornado por start_batch

transcribe_batch (interativo)

Processa arquivos um por vez com pré-visualização e confirmação antes de cada um. Útil quando você deseja revisar conforme avança.

ParâmetroDescrição
folder_pathCaminho para a pasta (obrigatório)
file_indexQual arquivo processar (baseado em 1). Omita para listar os arquivos primeiro.
languageCódigo do idioma. Padrão: en
recursiveIncluir subpastas
output_formattimestamps (padrão) ou text
privacy_modeSubstitui o modo privado. Confirmação necessária antes de cada arquivo; apenas metadados são retornados.

generate_subtitles

Gera arquivos de legenda. Suporta detecção automática de idioma e saída de tradução para inglês. Gera SRT (maior compatibilidade) ou WebVTT (web e vídeo HTML5).

ParâmetroDescrição
file_pathCaminho para o arquivo (obrigatório)
languageCódigo do idioma ou auto para detectar. Padrão: en
output_formatsrt (padrão) ou vtt
translate_to_englishTambém gera um arquivo de legenda com tradução para inglês. Aplica-se somente quando a origem não está em inglês.
backgroundExecuta como tarefa em segundo plano. Retorna um ID de tarefa para check_progress.
threadsSubstituição de threads da CPU

Quando tanto o idioma nativo quanto a tradução são solicitados, dois arquivos são salvos ao lado da origem:

  • filename.ja.srt — idioma original
  • filename.en.srt — tradução para inglês

A tradução integrada do Whisper só traduz para inglês. Para outros idiomas de destino, traduza o conteúdo do arquivo de legenda separadamente.


analyze_media

Analisa arquivos antes de se comprometer com a transcrição. Retorna duração, tamanho, codec e tempo estimado de transcrição em CPU e GPU. Para pastas, mostra todos os arquivos em uma tabela classificável com status de transcrição.

ParâmetroDescrição
pathCaminho para um único arquivo ou pasta (obrigatório)
sort_byPara pastas: duration (padrão), name ou size

check_config

Verifica se whisper-cli.exe, o arquivo de modelo e o FFmpeg estão todos acessíveis. Execute isto primeiro se algo estiver falhando.


list_models

Lista todos os arquivos de modelo Whisper instalados no seu diretório de modelos. Mostra nome do arquivo, tamanho, se está atualmente ativo, status de quantização e caso de uso recomendado. Sem chamadas de rede — lê apenas o sistema de arquivos local.


download_model

Baixa um modelo Whisper diretamente do Hugging Face para o seu diretório de modelos. Baixa apenas de namespaces confiáveis do Hugging Face. Após o download, use switch_model para ativá-lo.

ParâmetroDescrição
model_nameNome do modelo para baixar, ex.: large-v3-turbo, large-v3-turbo-q5_0, medium.en-q5_0

switch_model

Alterna o modelo Whisper ativo para a sessão atual sem reiniciar o Claude Desktop. A alteração tem escopo de sessão — não persiste após reiniciar. Para tornar permanente, atualize WHISPER_MODEL na sua configuração.

ParâmetroDescrição
model_nameNome do arquivo do modelo (ex.: ggml-large-v3-turbo.bin) ou caminho completo. Deve ser um arquivo .bin no diretório de modelos configurado.

check_system

Detecta o hardware de GPU e verifica se a aceleração Vulkan está disponível. Informa o nome da GPU, VRAM, se ggml-vulkan.dll está presente e recomenda o melhor tamanho de modelo para o seu hardware.


whisper_server

Inicia, para ou verifica o servidor de modelo persistente (whisper-server do whisper.cpp). Enquanto estiver em execução, o modelo ativo permanece residente na VRAM e cada chamada transcribe_audio / transcribe_batch é atendida via localhost sem recarregar o modelo por arquivo — um grande ganho de velocidade ao transcrever muitos arquivos curtos, onde o custo único de carregamento do modelo normalmente domina.

ParâmetroDescrição
actionstart — inicia com o modelo ativo residente; stop — encerra e libera a VRAM; status — informa o estado de execução, modelo residente, porta e tempo de atividade.
  • ⚠️ O modelo residente ocupa a VRAM da GPU durante toda a vida útil do servidor. Inicie-o deliberadamente, faça seu trabalho e depois use stop para devolver a GPU a outros aplicativos que compartilham a placa. A parada executa um encerramento completo para que a VRAM seja realmente liberada.
  • switch_model enquanto o servidor está em execução troca o modelo residente em tempo real (sem reiniciar).
  • Vinculado apenas a 127.0.0.1 — nunca exposto na rede.
  • Enquanto o servidor estiver ativo, operações que precisam da CLI de uso único — trabalhos em segundo plano, start_batch, generate_subtitles, saída lrc/csv e opções avançadas por chamada que a API HTTP não suporta (beam_size, best_of, word_timestamps, diarize, tinydiarize, vad_model, offset_t, duration) — são recusadas com uma mensagem de "pare o servidor primeiro" em vez de serem ignoradas silenciosamente, para que nenhum segundo mecanismo dispute a GPU.
  • Requer whisper-server.exe (acompanha whisper-cli.exe). Configure com WHISPER_SERVER_PATH / WHISPER_SERVER_PORT se necessário.

Formatos suportados

TipoFormatos
Nativos (sem conversão)mp3, wav
Vídeo (convertido automaticamente via FFmpeg)mp4, mkv, avi, mov, webm, flv, wmv, m4v, ts, 3gp
Áudio (convertido automaticamente via FFmpeg)m4a, ogg, flac

Aceleração de GPU

A versão pré-compilada com Vulkan ativa a aceleração de GPU automaticamente. Testada em AMD Radeon RX Vega 56 (5ª geração GCN). Qualquer GPU com suporte a Vulkan 1.0+ deve funcionar, incluindo NVIDIA e Intel Arc.

Comparação de desempenho (modelo large-v3, arquivo de áudio de ~14 minutos):

HardwareTempo
Somente CPU (Ryzen 7 2700x, 8 threads)~22 minutos (estimado)
GPU (Vega 56 via Vulkan)~3m 22s

A utilização da GPU durante a transcrição é tipicamente de 15–20%, voltando ao estado ocioso entre arquivos.

Suporta Windows 10 e Windows 11. Nenhuma configuração específica do Windows 11 é necessária — a ferramenta não faz chamadas à API Win32 e funciona em ambos os sistemas operacionais.


Suporte multilíngue

O Whisper pode detectar automaticamente o idioma falado e transcrever nesse idioma. O modelo de tradução integrado traduz apenas para o inglês.

Para melhor precisão multilíngue, use o modelo large-v3. Modelos específicos para inglês (*.en.bin) não conseguem detectar ou transcrever outros idiomas.

Exemplo — vídeo em idioma estrangeiro com legendas:

  1. Peça ao Claude para gerar legendas com language=auto e translate_to_english=true
  2. O Whisper detecta o idioma e gera um SRT ou VTT no idioma nativo
  3. Uma segunda passada gera uma tradução para o inglês
  4. Carregue o SRT no VLC via Legenda → Adicionar arquivo de legenda, ou use o VTT em qualquer player web

Privacidade e conformidade

O whisper-windows-mcp inclui uma arquitetura de privacidade integrada para conteúdo sensível e regulamentado.

Áudio e vídeo nunca saem da sua máquina. Essa garantia é incondicional.

O texto da transcrição é diferente — quando retornado inline em uma resposta de ferramenta, ele é processado pela API do Claude. Para a maioria dos usuários, esse é o comportamento esperado. Para conteúdo regulamentado (médico, jurídico, financeiro, corporativo), o modo de privacidade evita isso.

O modo de privacidade restringe todas as respostas das ferramentas apenas a metadados (nome do arquivo, contagem de palavras, caminho de salvamento). Nenhum texto de transcrição é transmitido à API do Claude em nenhuma circunstância. Ative por chamada com privacy_mode=true em qualquer ferramenta de transcrição, ou globalmente via WHISPER_PRIVACY_MODE=true na sua configuração.

Portão de consentimento — no primeiro uso por sessão no modo padrão, uma divulgação completa de privacidade é exibida antes que qualquer texto de transcrição seja retornado. Você deve confirmar explicitamente antes de continuar. Defina WHISPER_CONSENT_ACKNOWLEDGED=true na sua configuração para pular isso em conteúdo não sensível.

Consulte PRIVACY.md para orientações completas de conformidade (HIPAA, GDPR, privilégio advogado-cliente, FERPA, SOX, PCI-DSS).


Projetado para usuários do plano gratuito

Esta ferramenta foi criada para minimizar as interações com a API do Claude. Todo o fluxo de trabalho de transcrição — escanear, analisar, enfileirar, executar, validar — é projetado para exigir o mínimo possível de interações com o Claude. O trabalho pesado é feito localmente na sua máquina.


Variáveis de ambiente opcionais

VariávelDescrição
WHISPER_CLI_PATHCaminho para whisper-cli.exe (obrigatório)
WHISPER_MODELCaminho para o arquivo .bin do modelo (obrigatório)
WHISPER_THREADSSubstituição da contagem de threads da CPU
WHISPER_GPU_DEVICEÍndice do dispositivo Vulkan para fixar a transcrição, para sistemas com múltiplas GPUs (o índice de enumeração do Vulkan — verifique o log de inicialização do whisper-cli; não é a ordem de GPUs do Windows). Substituível por chamada com gpu_device. Consulte TROUBLESHOOTING.md.
WHISPER_FOREGROUND_MAX_SECLimite de transcrição em primeiro plano em segundos (padrão 210). Arquivos com tempo estimado maior são roteados para o modo em segundo plano em vez de arriscar o timeout de ~4 minutos da ferramenta do Claude Desktop.
FFMPEG_PATHCaminho para o ffmpeg se não estiver no PATH do sistema
WHISPER_SERVER_PATHCaminho para whisper-server.exe para o servidor de modelo persistente (padrão: junto de whisper-cli.exe). Consulte a ferramenta whisper_server.
WHISPER_SERVER_PORTPorta localhost para o servidor de modelo persistente (padrão 8571). Sempre vinculado a 127.0.0.1.
WHISPER_PRIVACY_MODEQuando true, todas as respostas das ferramentas retornam apenas metadados — nenhum texto de transcrição é transmitido à API do Claude. Para conteúdo regulamentado ou confidencial. Pode ser substituído por chamada com o parâmetro privacy_mode. Consulte PRIVACY.md.
WHISPER_CONSENT_ACKNOWLEDGEDQuando true, pula a divulgação única de consentimento da sessão exibida antes do retorno do texto de transcrição. Defina depois de entender o limite de privacidade e não precisar mais do lembrete. Não tem efeito quando o modo de privacidade está ativo.

Segurança

Verificação do binário. Para verificar a integridade do binário whisper-cli.exe na versão pré-compilada, verifique o hash SHA256 no PowerShell:

Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256

O hash esperado para o binário da versão v1.4.0 está documentado na página de releases.

Validação de entrada. Todos os caminhos de arquivos e pastas são validados antes do uso, em todas as ferramentas que os recebem — caminhos UNC (\\server\share) e sequências de travessia de diretório (..) são rejeitados. Arquivos acima de 10 GB são rejeitados para evitar esgotamento de recursos. job_id e batch_id são verificados contra o formato exato gerado pelo servidor antes de serem usados para construir qualquer caminho de arquivo, para que um ID malicioso não possa sair do diretório de trabalhos.

Conscientização sobre injeção via transcrição. Arquivos de áudio podem conter conteúdo falado que, quando transcrito, se assemelha a instruções. As defesas integradas do Claude lidam com isso, mas vale saber que o conteúdo da transcrição é tratado como dados — nunca como instruções — pelo próprio servidor MCP. Como o conteúdo transcrito ainda pode influenciar quais ferramentas o Claude chamará em seguida, a validação de caminho/ID é aplicada de forma defensiva, em vez de confiar apenas na suposição de usuário único.

Downloads de modelos são restritos. A ferramenta download_model só baixa de dois namespaces confiáveis do Hugging Face (ggerganov/whisper.cpp e ggml-org). URLs arbitrárias são rejeitadas. Redirecionamentos são validados contra uma lista de permissões antes de serem seguidos. (Os downloads ainda não são verificados contra um digest SHA256 por modelo — consulte SECURITY.md.)

A seleção de modelos é isolada. Tanto switch_model quanto a substituição transcribe_audio model aceitam apenas arquivos .bin dentro do diretório de modelos configurado. Caminhos fora desse diretório são rejeitados por meio de contenção de caminho normalizado.

Sem sombreamento de PATH. Os binários do sistema que o servidor invoca em seu nome (tasklist, wmic) são chamados por caminho System32 absoluto para que não possam ser sombreados por um executável de mesmo nome mais à frente no PATH.

Consulte SECURITY.md para a política de segurança completa.


Solução de problemas

Consulte TROUBLESHOOTING.md para soluções detalhadas. Consulte PRIVACY.md para orientações de conformidade se você lidar com conteúdo regulamentado.

Lista de verificação rápida:

  • Caminhos na configuração usam barras invertidas duplas (C:\\whisper\\...)
  • whisper-cli.exe existe no caminho configurado
  • O arquivo .bin do modelo existe no caminho configurado
  • O FFmpeg está instalado e no PATH (ffmpeg -version funciona)
  • O Claude Desktop foi totalmente reiniciado após editar a configuração
  • O Whisper mostra em execução em Configurações → Desenvolvedor

Licença

Uso não comercial: MIT — gratuito para uso pessoal, educacional e não comercial. Consulte LICENSE.

Uso comercial: Uma licença comercial separada é necessária para qualquer uso empresarial, profissional ou que gere receita. Consulte COMMERCIAL-LICENSE.md para termos e informações de contato.

Contribuição

Pull requests são bem-vindos. Consulte ROADMAP.md para recursos planejados.

Se você testou a aceleração de GPU em hardware não listado acima, abra uma issue com seus resultados — modelo da GPU, VRAM, tamanho do modelo e throughput observado.