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
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-mcppopular 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
- Node.js 18 ou superior — nodejs.org
- Binários whisper.cpp com suporte a GPU Vulkan — veja o Passo 1
- Um arquivo de modelo Whisper — veja o Passo 2
- 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
| Modelo | Tamanho | Velocidade | Precisão | Melhor para |
|---|---|---|---|---|
ggml-tiny.en.bin | 75 MB | Muito rápido | Básica | Testes rápidos |
ggml-base.en.bin | 142 MB | Rápido | Boa | Inglês do dia a dia |
ggml-small.en.bin | 466 MB | Moderado | Melhor | Gravações importantes |
ggml-medium.en.bin | 1,5 GB | Rápido na GPU | Muito boa | Melhor qualidade em inglês |
ggml-large-v3-turbo.bin | 1,6 GB | Rápido na GPU | Excelente | Recomendado 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.bin | 2,9 GB | Rápido na GPU | Excelente | Multilíngue, precisão máxima |
ggml-medium.en-q5_0.bin | 514 MB | Rápido | Muito boa | Melhor opção em inglês apenas com CPU — alta precisão com baixo uso de memória |
ggml-large-v3-turbo-q5_0.bin | 547 MB | Rápido | Excelente | Melhor opção multilíngue apenas com CPU |
ggml-large-v3-q5_0.bin | 1,1 GB | Moderado na CPU | Excelente | Multilí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âmetro | Descrição |
|---|---|
file_path | Caminho absoluto para o arquivo (obrigatório) |
language | Código do idioma (en, ja, es, etc.) ou auto para detectar. Padrão: en |
output_format | timestamps (padrão), text, json, srt, vtt, lrc ou csv |
save_to_file | Salva a transcrição como .txt ao lado do arquivo de origem |
background | Executa 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_mode | Substitui 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. |
threads | Substituição de threads da CPU |
temperature | Temperatura de amostragem 0,0–1,0. Padrão 0,0 (determinístico). |
prompt | String 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_text | Reativa o condicionamento de contexto entre segmentos. Padrão falso. |
beam_size | Largura da busca em feixe. Maior = mais preciso, mais lento. Padrão 5. |
best_of | Sequências candidatas avaliadas. Padrão 5. |
gpu_device | Índice do dispositivo GPU para sistemas multi-GPU. Padrão 0. |
processors | Contagem de processadores paralelos. Padrão 1. |
word_timestamps | Uma palavra por segmento com timestamp. Útil para alinhamento de clipes. |
max_segment_length | Comprimento máximo do segmento em caracteres. |
diarize | Diarização de falantes estéreo — requer áudio estéreo com falantes em canais separados. |
tinydiarize | Detecçã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_model | Caminho para o modelo VAD Silero .bin. Remove silêncios antes da transcrição — reduz alucinações em arquivos ruidosos. |
offset_t | Deslocamento inicial em milissegundos. |
duration | Duraçã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 tempojson— JSON estruturado (somente modo bloqueante)srt— arquivo de legenda SubRip salvo ao lado da origemvtt— arquivo de legenda WebVTT salvo ao lado da origemlrc— formato LRC de letras/karaokê salvo ao lado da origemcsv— 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âmetro | Descrição |
|---|---|
job_id | ID da tarefa retornado por transcribe_audio |
privacy_mode | Substitui 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âmetro | Descrição |
|---|---|
folder_path | Caminho para a pasta (obrigatório) |
language | Código do idioma. Padrão: en |
threads | Substituição de threads da CPU |
output_format | timestamps (padrão) ou text |
privacy_mode | Substitui 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âmetro | Descrição |
|---|---|
batch_id | ID 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âmetro | Descrição |
|---|---|
folder_path | Caminho para a pasta (obrigatório) |
file_index | Qual arquivo processar (baseado em 1). Omita para listar os arquivos primeiro. |
language | Código do idioma. Padrão: en |
recursive | Incluir subpastas |
output_format | timestamps (padrão) ou text |
privacy_mode | Substitui 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âmetro | Descrição |
|---|---|
file_path | Caminho para o arquivo (obrigatório) |
language | Código do idioma ou auto para detectar. Padrão: en |
output_format | srt (padrão) ou vtt |
translate_to_english | Também gera um arquivo de legenda com tradução para inglês. Aplica-se somente quando a origem não está em inglês. |
background | Executa como tarefa em segundo plano. Retorna um ID de tarefa para check_progress. |
threads | Substituiçã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 originalfilename.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âmetro | Descrição |
|---|---|
path | Caminho para um único arquivo ou pasta (obrigatório) |
sort_by | Para 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âmetro | Descrição |
|---|---|
model_name | Nome 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âmetro | Descrição |
|---|---|
model_name | Nome 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âmetro | Descrição |
|---|---|
action | start — 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
stoppara devolver a GPU a outros aplicativos que compartilham a placa. A parada executa um encerramento completo para que a VRAM seja realmente liberada. switch_modelenquanto 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ídalrc/csve 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(acompanhawhisper-cli.exe). Configure comWHISPER_SERVER_PATH/WHISPER_SERVER_PORTse necessário.
Formatos suportados
| Tipo | Formatos |
|---|---|
| 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):
| Hardware | Tempo |
|---|---|
| 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:
- Peça ao Claude para gerar legendas com
language=autoetranslate_to_english=true - O Whisper detecta o idioma e gera um SRT ou VTT no idioma nativo
- Uma segunda passada gera uma tradução para o inglês
- 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ável | Descrição |
|---|---|
WHISPER_CLI_PATH | Caminho para whisper-cli.exe (obrigatório) |
WHISPER_MODEL | Caminho para o arquivo .bin do modelo (obrigatório) |
WHISPER_THREADS | Substituiçã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_SEC | Limite 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_PATH | Caminho para o ffmpeg se não estiver no PATH do sistema |
WHISPER_SERVER_PATH | Caminho para whisper-server.exe para o servidor de modelo persistente (padrão: junto de whisper-cli.exe). Consulte a ferramenta whisper_server. |
WHISPER_SERVER_PORT | Porta localhost para o servidor de modelo persistente (padrão 8571). Sempre vinculado a 127.0.0.1. |
WHISPER_PRIVACY_MODE | Quando 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_ACKNOWLEDGED | Quando 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.exeexiste no caminho configurado- O arquivo
.bindo modelo existe no caminho configurado - O FFmpeg está instalado e no PATH (
ffmpeg -versionfunciona) - 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.