whisper-windows-mcp

Transcripción local de audio/video acelerada por GPU para Claude Desktop en Windows, utilizando whisper.cpp con soporte AMD Vulkan, procesamiento por lotes en segundo plano y generación de subtítulos.

Documentación

whisper-windows-mcp

CI

whisper-windows-mcp MCP server

Un servidor MCP (Model Context Protocol) nativo de Windows que permite a Claude Desktop transcribir archivos de audio y vídeo localmente usando whisper.cpp — con aceleración GPU, soporte multilingüe y procesamiento por lotes. Toda la transcripción se ejecuta localmente — ningún audio, vídeo o ruta de archivo sale jamás de tu máquina.

¿Por qué existe esto? El popular paquete whisper-mcp fue creado para macOS y asume un entorno Unix. No funciona en Windows. Este paquete fue escrito específicamente para usuarios de Windows que quieren transcripción de IA local integrada con Claude Desktop.


Lo que puedes hacer con él

Una vez instalado, puedes decir cosas como estas directamente en Claude Desktop:

  • "Transcribe C:\Users\Me\Downloads\meeting.mp3"
  • "Transcribe esta carpeta de grabaciones y guarda cada una como archivo de texto"
  • "Genera subtítulos en japonés e inglés para este vídeo"
  • "Inicia una transcripción por lotes de todo lo que hay en esta carpeta"
  • "¿Cuánto tardará en transcribir estos archivos?"
  • "Comprueba si la aceleración GPU está funcionando"
  • "Transcribe este archivo en modo privacidad"

Requisitos

  1. Node.js 18 o posterior — nodejs.org
  2. Binarios de whisper.cpp con soporte GPU Vulkan — ver Paso 1
  3. Un archivo de modelo Whisper — ver Paso 2
  4. FFmpeg — necesario para archivos de vídeo y audio que no sea WAV/MP3

Paso 1 — Instalar los binarios de whisper.cpp

Opción A — Versión Vulkan precompilada (recomendada)

Descarga whisper-vulkan-win-x64.zip desde la página de versiones.

Esta es una compilación personalizada con aceleración GPU Vulkan habilitada. Funciona con GPUs AMD, NVIDIA e Intel — no se requiere SDK específico del fabricante.

Extrae en C:\whisper\Release\. Deberías obtener:

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

La aceleración GPU es automática — no se necesita configuración adicional.

Opción B — Compilar desde el código fuente

Requiere: Git, CMake, Visual Studio Build Tools 2022+ con "Desarrollo de escritorio con C++", SDK de Vulkan desde 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

Copia los binarios de build\bin\Release\ a C:\whisper\Release\.

Nota: Las versiones oficiales de whisper.cpp para Windows en GitHub no incluyen una compilación Vulkan. Debes usar la versión precompilada anterior o compilar desde el código fuente con -DGGML_VULKAN=ON.


Paso 2 — Descargar un modelo Whisper

ModeloTamañoVelocidadPrecisiónIdeal para
ggml-tiny.en.bin75 MBMuy rápidaBásicaPruebas rápidas
ggml-base.en.bin142 MBRápidaBuenaInglés cotidiano
ggml-small.en.bin466 MBModeradaMejorGrabaciones importantes
ggml-medium.en.bin1.5 GBRápida en GPUMuy buenaInglés de máxima calidad
ggml-large-v3-turbo.bin1.6 GBRápida en GPUExcelenteRecomendado para trabajo por lotes en inglés con GPU — ~6x más rápido que large-v3 con pérdida mínima de precisión
ggml-large-v3.bin2.9 GBRápida en GPUExcelenteMultilingüe, máxima precisión
ggml-medium.en-q5_0.bin514 MBRápidaMuy buenaMejor opción solo CPU en inglés — alta precisión con bajo consumo de memoria
ggml-large-v3-turbo-q5_0.bin547 MBRápidaExcelenteMejor opción multilingüe solo CPU
ggml-large-v3-q5_0.bin1.1 GBModerada en CPUExcelenteMultilingüe, apta para CPU

Usa download_model en Claude Desktop para instalar cualquiera de estos directamente. Para uso solo en inglés: large-v3-turbo (GPU) o medium.en-q5_0 (CPU) son los mejores puntos de partida. Para uso multilingüe: large-v3-turbo o large-v3-turbo-q5_0 (CPU). Los modelos solo en inglés (*.en.bin) generan [FOREIGN] en audio que no sea inglés y no pueden usarse para otros idiomas.


Paso 3 — Instalar FFmpeg

FFmpeg es necesario para archivos de vídeo y formatos de audio no nativos.

Instala mediante winget:

winget install ffmpeg

O descárgalo desde ffmpeg.org y añádelo a tu PATH.

Verifica:

ffmpeg -version

Paso 4 — Instalar este servidor MCP

npm install -g whisper-windows-mcp

Paso 5 — Configurar Claude Desktop

Abre Claude Desktop → Settings → Developer → Edit Config.

Añade la 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"
      }
    }
  }
}

Ubicación del archivo de configuración: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Usa doble barra invertida en todas las rutas.

Guarda y reinicia por completo Claude Desktop. Deberías ver whisper listado con una insignia verde de ejecución en Settings → Developer.


Paso 6 — Verificar tu configuración

En Claude Desktop, pregunta:

"Comprueba tu configuración de whisper"

Luego:

"Comprueba el hardware de tu sistema"

Esto confirma que tu GPU está detectada y que la aceleración Vulkan está activa.


Herramientas disponibles

transcribe_audio

Transcribe un solo archivo. Admite modo bloqueante (predeterminado) o modo en segundo plano para archivos largos.

ParámetroDescripción
file_pathRuta absoluta al archivo (obligatorio)
languageCódigo de idioma (en, ja, es, etc.) o auto para detectar. Predeterminado: en
output_formattimestamps (predeterminado), text, json, srt, vtt, lrc o csv
save_to_fileGuarda la transcripción como .txt junto al archivo de origen
backgroundEjecutar como trabajo independiente — devuelve un ID de trabajo inmediatamente. Usa check_progress para supervisarlo. Recomendado para archivos de más de 10 minutos.
privacy_modeAnula el modo privacidad para esta llamada. true = solo metadatos, sin texto de transcripción transmitido. false = devolver texto incluso si WHISPER_PRIVACY_MODE=true está activo globalmente. Omitir para usar la configuración global.
threadsAnulación de hilos de CPU
temperatureTemperatura de muestreo 0.0–1.0. Predeterminado 0.0 (determinista).
promptCadena de contexto previo — mejora la precisión para vocabulario específico del dominio o nombres de hablantes. Ejemplo: "Names: Keemstar, DramaAlert."
condition_on_prev_textRehabilitar el condicionamiento de contexto entre segmentos. Predeterminado: false.
beam_sizeAmplitud de búsqueda de haz. Mayor = más preciso, más lento. Predeterminado: 5.
best_ofSecuencias candidatas evaluadas. Predeterminado: 5.
gpu_deviceÍndice de dispositivo GPU para sistemas multi-GPU. Predeterminado: 0.
processorsNúmero de procesadores en paralelo. Predeterminado: 1.
word_timestampsUna palabra por segmento con marca de tiempo. Útil para alineación de clips.
max_segment_lengthLongitud máxima de segmento en caracteres.
diarizeDiarización de hablantes en estéreo — requiere audio estéreo con hablantes en canales separados.
tinydiarizeDetección de turnos de hablante en mono — marca [SPEAKER_TURN] en los cambios de hablante en audio de un solo canal. Requiere un modelo tdrz: download_model small.en-tdrz, luego switch_model ggml-small.en-tdrz.bin.
vad_modelRuta al modelo VAD de Silero .bin. Elimina el silencio antes de la transcripción — reduce alucinaciones en archivos ruidosos.
offset_tDesplazamiento de inicio en milisegundos.
durationDuración del procesamiento en milisegundos desde el desplazamiento.

Formatos de salida:

  • timestamps — segmentos con marca de tiempo, p. ej. [00:00:01.230 --> 00:00:04.560] Hello world (predeterminado)
  • text — texto plano, sin códigos de tiempo
  • json — JSON estructurado (solo modo bloqueante)
  • srt — archivo de subtítulos SubRip guardado junto al origen
  • vtt — archivo de subtítulos WebVTT guardado junto al origen
  • lrc — formato LRC de letras/karaoke guardado junto al origen
  • csv — CSV con marcas de tiempo guardado junto al origen

check_progress

Supervisa un trabajo de transcripción en segundo plano iniciado con transcribe_audio (background=true).

Devuelve el tiempo transcurrido, la última marca de tiempo procesada y la transcripción completa cuando termina.

ParámetroDescripción
job_idID de trabajo devuelto por transcribe_audio
privacy_modeAnula el modo privacidad para esta comprobación. true = solo metadatos, independientemente de cómo se inició el trabajo.

start_batch

Transcripción por lotes secuencial automatizada de todos los archivos no transcritos en una carpeta. Ordena por duración (primero los más cortos), procesa uno a la vez como trabajos en segundo plano y valida cada salida. El lote avanza automáticamente cuando cada archivo termina — no se requiere sondeo.

ParámetroDescripción
folder_pathRuta a la carpeta (obligatorio)
languageCódigo de idioma. Predeterminado: en
threadsAnulación de hilos de CPU
output_formattimestamps (predeterminado) o text
privacy_modeAnula el modo privacidad. Se requiere una confirmación antes de iniciar el lote; luego todos los archivos se procesan sin supervisión. No se devuelve texto de transcripción.

check_batch_progress

Supervisa un lote en ejecución. Avanza automáticamente al siguiente archivo cuando el actual termina. Devuelve el progreso general, el archivo actual con marca de tiempo y cualquier archivo con errores.

ParámetroDescripción
batch_idID de lote devuelto por start_batch

transcribe_batch (interactivo)

Procesa archivos uno a la vez con una vista previa y confirmación antes de cada uno. Útil cuando quieres revisar sobre la marcha.

ParámetroDescripción
folder_pathRuta a la carpeta (obligatorio)
file_indexQué archivo procesar (basado en 1). Omitir para listar los archivos primero.
languageCódigo de idioma. Predeterminado: en
recursiveIncluir subcarpetas
output_formattimestamps (predeterminado) o text
privacy_modeAnula el modo privacidad. Se requiere confirmación antes de cada archivo; solo se devuelven metadatos.

generate_subtitles

Genera archivos de subtítulos. Admite detección automática de idioma y salida de traducción al inglés. Genera SRT (máxima compatibilidad) o WebVTT (web y vídeo HTML5).

ParámetroDescripción
file_pathRuta al archivo (obligatorio)
languageCódigo de idioma o auto para detectar. Predeterminado: en
output_formatsrt (predeterminado) o vtt
translate_to_englishGenera también un archivo de subtítulos con traducción al inglés. Solo se aplica cuando el origen no es inglés.
backgroundEjecutar como trabajo en segundo plano independiente. Devuelve un ID de trabajo para check_progress.
threadsAnulación de hilos de CPU

Cuando se solicitan tanto el idioma nativo como la traducción, se guardan dos archivos junto al origen:

  • filename.ja.srt — idioma original
  • filename.en.srt — traducción al inglés

La traducción integrada de Whisper solo traduce al inglés. Para otros idiomas de destino, traduce el contenido del archivo de subtítulos por separado.


analyze_media

Analiza archivos antes de comprometerse a la transcripción. Devuelve duración, tamaño, códec y tiempo estimado de transcripción en CPU y GPU. Para carpetas, muestra todos los archivos en una tabla ordenable con el estado de transcripción.

ParámetroDescripción
pathRuta a un solo archivo o carpeta (obligatorio)
sort_byPara carpetas: duration (predeterminado), name o size

check_config

Verifica que whisper-cli.exe, el archivo de modelo y FFmpeg sean accesibles. Ejecuta esto primero si algo falla.


list_models

Lista todos los archivos de modelo Whisper instalados en tu directorio de modelos. Muestra nombre de archivo, tamaño, si está activo actualmente, estado de cuantización y caso de uso recomendado. Sin llamadas de red — solo lee el sistema de archivos local.


download_model

Descarga un modelo Whisper directamente desde Hugging Face a tu directorio de modelos. Solo descarga desde espacios de nombres de Hugging Face de confianza. Después de descargar, usa switch_model para activarlo.

ParámetroDescripción
model_nameNombre del modelo a descargar, p. ej. large-v3-turbo, large-v3-turbo-q5_0, medium.en-q5_0

switch_model

Cambia el modelo Whisper activo para la sesión actual sin reiniciar Claude Desktop. El cambio tiene alcance de sesión — no persiste después del reinicio. Para hacerlo permanente, actualiza WHISPER_MODEL en tu configuración.

ParámetroDescripción
model_nameNombre del archivo de modelo (p. ej. ggml-large-v3-turbo.bin) o ruta completa. Debe ser un archivo .bin en el directorio de modelos configurado.

check_system

Detecta el hardware de GPU y verifica que la aceleración Vulkan esté disponible. Informa el nombre de la GPU, la VRAM, si ggml-vulkan.dll está presente, y recomienda el mejor tamaño de modelo para tu hardware.


whisper_server

Inicia, detiene o verifica el servidor de modelo persistente (whisper-server de whisper.cpp). Mientras está en ejecución, el modelo activo permanece residente en la VRAM y cada llamada transcribe_audio / transcribe_batch se sirve a través de localhost sin recargar el modelo por archivo — una gran aceleración al transcribir muchos archivos cortos, donde el costo único de carga del modelo de otro modo domina.

ParámetroDescripción
actionstart — inicia con el modelo activo residente; stop — apaga y libera la VRAM; status — informa el estado de ejecución, el modelo residente, el puerto y el tiempo de actividad.
  • ⚠️ El modelo residente ocupa la VRAM de la GPU durante toda la vida del servidor. Inícialo deliberadamente, haz tu trabajo y luego stop para devolver la GPU a otras aplicaciones que comparten la tarjeta. Detenerlo realiza un cierre completo para que la VRAM se libere realmente.
  • switch_model mientras el servidor está en ejecución intercambia en caliente el modelo residente (sin reinicio).
  • Vinculado solo a 127.0.0.1 — nunca expuesto en la red.
  • Mientras el servidor está activo, las operaciones que necesitan la CLI de un solo uso — trabajos en segundo plano, start_batch, generate_subtitles, salida lrc/csv, y opciones avanzadas por llamada que la API HTTP no respeta (beam_size, best_of, word_timestamps, diarize, tinydiarize, vad_model, offset_t, duration) — se rechazan con un mensaje de "detén primero el servidor" en lugar de ignorarse silenciosamente, de modo que ningún segundo motor compite jamás por la GPU.
  • Requiere whisper-server.exe (se incluye junto con whisper-cli.exe). Configúralo con WHISPER_SERVER_PATH / WHISPER_SERVER_PORT si es necesario.

Formatos compatibles

TipoFormatos
Nativo (sin conversión)mp3, wav
Video (convertido automáticamente con FFmpeg)mp4, mkv, avi, mov, webm, flv, wmv, m4v, ts, 3gp
Audio (convertido automáticamente con FFmpeg)m4a, ogg, flac

Aceleración de GPU

La versión precompilada de Vulkan habilita la aceleración de GPU automáticamente. Probada en AMD Radeon RX Vega 56 (5.ª generación GCN). Cualquier GPU con soporte Vulkan 1.0+ debería funcionar, incluidas NVIDIA e Intel Arc.

Comparación de rendimiento (modelo large-v3, archivo de audio de ~14 minutos):

HardwareTiempo
Solo CPU (Ryzen 7 2700x, 8 hilos)~22 minutos (estimado)
GPU (Vega 56 vía Vulkan)~3m 22s

La utilización de la GPU durante la transcripción suele ser del 15–20 %, volviendo a inactiva entre archivos.

Compatible con Windows 10 y Windows 11. No se requiere configuración específica de Windows 11 — la herramienta no realiza llamadas a la API Win32 y funciona en cualquiera de los dos sistemas operativos.


Soporte multilingüe

Whisper puede detectar automáticamente el idioma hablado y transcribir en ese idioma. El modelo de traducción integrado traduce solo al inglés.

Para obtener la mejor precisión multilingüe, usa el modelo large-v3. Los modelos específicos de inglés (*.en.bin) no pueden detectar ni transcribir otros idiomas.

Ejemplo — video en idioma extranjero con subtítulos:

  1. Pide a Claude que genere subtítulos con language=auto y translate_to_english=true
  2. Whisper detecta el idioma y genera un SRT o VTT en el idioma nativo
  3. Una segunda pasada genera una traducción al inglés
  4. Carga el SRT en VLC mediante Subtítulos → Añadir archivo de subtítulos, o usa el VTT en cualquier reproductor web

Privacidad y cumplimiento

whisper-windows-mcp incluye una arquitectura de privacidad integrada para contenido sensible y regulado.

El audio y el video nunca salen de tu máquina. Esta garantía es incondicional.

El texto de la transcripción es diferente — cuando se devuelve en línea en una respuesta de herramienta, es procesado por la API de Claude. Para la mayoría de los usuarios, este es el comportamiento esperado. Para contenido regulado (médico, legal, financiero, corporativo), el modo de privacidad lo evita.

El modo de privacidad restringe todas las respuestas de herramientas solo a metadatos (nombre de archivo, recuento de palabras, ruta de guardado). Ningún texto de transcripción se transmite a la API de Claude bajo ninguna circunstancia. Actívalo por llamada con privacy_mode=true en cualquier herramienta de transcripción, o globalmente mediante WHISPER_PRIVACY_MODE=true en tu configuración.

Puerta de consentimiento — en el primer uso por sesión en modo estándar, se muestra una divulgación completa de privacidad antes de devolver cualquier texto de transcripción. Debes confirmar explícitamente antes de continuar. Establece WHISPER_CONSENT_ACKNOWLEDGED=true en tu configuración para omitir esto en contenido no sensible.

Consulta PRIVACY.md para obtener orientación completa sobre cumplimiento (HIPAA, GDPR, privilegio abogado-cliente, FERPA, SOX, PCI-DSS).


Diseñado para usuarios del plan gratuito

Esta herramienta está diseñada para minimizar las interacciones con la API de Claude. Todo el flujo de trabajo de transcripción — escanear, analizar, poner en cola, ejecutar, validar — está diseñado para requerir la menor cantidad posible de interacciones con Claude. El trabajo pesado se realiza localmente en tu máquina.


Variables de entorno opcionales

VariableDescripción
WHISPER_CLI_PATHRuta a whisper-cli.exe (obligatorio)
WHISPER_MODELRuta al archivo .bin del modelo (obligatorio)
WHISPER_THREADSAnulación del número de hilos de CPU
WHISPER_GPU_DEVICEÍndice de dispositivo Vulkan para fijar la transcripción, para sistemas con múltiples GPU (el índice de enumeración de Vulkan — consulta el registro de inicio de whisper-cli; no el orden de GPU de Windows). Se puede anular por llamada con gpu_device. Consulta TROUBLESHOOTING.md.
WHISPER_FOREGROUND_MAX_SECLímite de transcripción en primer plano en segundos (predeterminado 210). Los archivos que se estima que tardarán más se enrutan al modo de segundo plano en lugar de arriesgar el tiempo de espera de herramienta de ~4 minutos de Claude Desktop.
FFMPEG_PATHRuta a ffmpeg si no está en el PATH del sistema
WHISPER_SERVER_PATHRuta a whisper-server.exe para el servidor de modelo persistente (predeterminado: junto a whisper-cli.exe). Consulta la herramienta whisper_server.
WHISPER_SERVER_PORTPuerto de localhost para el servidor de modelo persistente (predeterminado 8571). Siempre vinculado a 127.0.0.1.
WHISPER_PRIVACY_MODECuando true, todas las respuestas de herramientas devuelven solo metadatos — ningún texto de transcripción se transmite a la API de Claude. Para contenido regulado o confidencial. Se puede anular por llamada con el parámetro privacy_mode. Consulta PRIVACY.md.
WHISPER_CONSENT_ACKNOWLEDGEDCuando true, omite la divulgación de consentimiento única por sesión que se muestra antes de devolver el texto de transcripción. Establécelo después de comprender el límite de privacidad y de no necesitar el recordatorio. No tiene efecto cuando el modo de privacidad está activo.

Seguridad

Verificación del binario. Para verificar la integridad del binario whisper-cli.exe en la versión precompilada, comprueba su hash SHA256 en PowerShell:

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

El hash esperado para el binario de la versión v1.4.0 está documentado en la página de versiones.

Validación de entrada. Todas las rutas de archivos y carpetas se validan antes de su uso, en cada herramienta que las recibe — las rutas UNC (\\server\share) y las secuencias de recorrido de directorios (..) se rechazan. Los archivos de más de 10 GB se rechazan para evitar el agotamiento de recursos. job_id y batch_id se verifican contra el formato exacto emitido por el servidor antes de usarse para construir cualquier ruta de archivo, de modo que un ID manipulado no pueda salirse del directorio de trabajos.

Conciencia sobre inyección en transcripciones. Los archivos de audio pueden contener contenido hablado que, al transcribirse, se asemeja a instrucciones. Las defensas integradas de Claude manejan esto, pero vale la pena saber que el contenido de la transcripción se trata como datos — nunca como instrucciones — por el propio servidor MCP. Debido a que el contenido transcrito aún puede influir en qué herramientas llama Claude a continuación, la validación de rutas/IDs se aplica de forma defensiva en lugar de confiar únicamente en la suposición de un solo usuario.

Las descargas de modelos están restringidas. La herramienta download_model solo descarga de dos espacios de nombres confiables de Hugging Face (ggerganov/whisper.cpp y ggml-org). Las URL arbitrarias se rechazan. Las redirecciones se validan contra una lista de permitidos antes de seguirlas. (Las descargas aún no se verifican contra un resumen SHA256 por modelo — consulta SECURITY.md).

La selección de modelos está aislada. Tanto switch_model como la anulación transcribe_audio model solo aceptan archivos .bin dentro del directorio de modelos configurado. Las rutas fuera de ese directorio se rechazan mediante contención de ruta normalizada.

Sin sombreado de PATH. Los binarios del sistema que el servidor invoca en tu nombre (tasklist, wmic) se llaman mediante ruta System32 absoluta para que no puedan ser sombreados por un ejecutable del mismo nombre que aparezca antes en PATH.

Consulta SECURITY.md para la política de seguridad completa.


Solución de problemas

Consulta TROUBLESHOOTING.md para soluciones detalladas. Consulta PRIVACY.md para orientación sobre cumplimiento si manejas contenido regulado.

Lista de verificación rápida:

  • Las rutas en la configuración usan doble barra invertida (C:\\whisper\\...)
  • whisper-cli.exe existe en la ruta configurada
  • El archivo .bin del modelo existe en la ruta configurada
  • FFmpeg está instalado y en el PATH (ffmpeg -version funciona)
  • Claude Desktop se reinició por completo después de editar la configuración
  • Whisper muestra en ejecución en Configuración → Desarrollador

Licencia

Uso no comercial: MIT — gratuito para uso personal, educativo y no comercial. Consulta LICENSE.

Uso comercial: Se requiere una licencia comercial separada para cualquier uso empresarial, profesional o que genere ingresos. Consulta COMMERCIAL-LICENSE.md para conocer los términos y la información de contacto.

Contribuciones

Se aceptan pull requests. Consulta ROADMAP.md para conocer las funciones planificadas.

Si has probado la aceleración de GPU en hardware no listado anteriormente, abre un issue con tus resultados — modelo de GPU, VRAM, tamaño del modelo y rendimiento observado.