whisper-windows-mcp

Purpose

whisper-windows-mcp is a Windows-native MCP (Model Context Protocol) server that lets Claude Desktop transcribe audio and video files locally using whisper.cpp. This project was written specifically for Windows users, because the popular whisper-mcp package is built for macOS and Unix environments and cannot be used on Windows. All transcription runs locally; audio, video, or file paths never leave your machine.

Main capabilities

• Single-file transcription, with blocking (default) or background mode, suitable for long files.
• Output formats: timestamps (segments with timestamps, default), text (plain text), json (blocking mode only), srt (SubRip subtitles), vtt (WebVTT subtitles), lrc (lyrics/karaoke format), csv (with timestamps). Subtitle and CSV files are saved alongside the source file.
• Background task monitoring: returns elapsed time, the last processed timestamp, and the full transcription text once complete.
• Batch transcription: automatically sorted by file duration (shortest first), processed one by one as background tasks, with each automatically advancing once complete, no polling required.
• Interactive batch transcription: processed one by one, with a preview and confirmation before each file.
• Subtitle generation: supports automatic language detection and English translation output, generating SRT or WebVTT. When both the native language and translation are requested, two files are saved: filename.ja.srt (native language) and filename.en.srt (English translation). Whisper's built-in translation only supports translation into English.
• File analysis: returns duration, size, codec, and estimated transcription time for CPU and GPU before transcription. For folders, displays a sortable table and transcription status.
• Configuration validation: checks whether whisper-cli.exe, the model file, and FFmpeg are accessible.
• Model management: lists installed models (filename, size, whether active, quantization status, recommended use cases), downloads models from Hugging Face (only from trusted namespaces), switches the active model in the current session (not retained after restart; WHISPER_MODEL must be changed in the configuration to take permanent effect).
• GPU detection: reports GPU name, VRAM, whether ggml-vulkan.dll iswhether it exists, and recommend a model size suitable for the hardware.
• Persistent model server: start whisper-server to keep the active model resident in VRAM, with all transcriptions served via localhost, avoiding reloading the model each time. Note: a resident model occupies VRAM for the entire server lifecycle and must be explicitly started and stopped. The server binds only to 127.0.0.1 and is not exposed to the network. While the server is running, operations requiring the one-shot CLI (background tasks, start_batch, generate_subtitles, lrc/csv output, and advanced options not supported by the HTTP API such as beam_size, best_of, word_timestamps, diarize, etc.) will be rejected with a prompt to stop the server first.

Usage

Prerequisites: Node.js 18 or later; whisper.cpp binaries with Vulkan GPU support (precompiled Vulkan release or built from source); a Whisper model file; FFmpeg for video files and non-WAV/MP3 audio.

Steps:

1. Install the whisper.cpp binaries. It is recommended to download whisper-vulkan-win-x64.zip from the releases page and extract it to C:\whisper\Release. This is a self-compiled version with Vulkan GPU acceleration enabled, suitable for AMD, NVIDIA, and Intel GPUs, with no vendor-specific SDK required. It can also be built from source (requires Git, CMake, Visual Studio Build Tools 2022+, and the Vulkan SDK), using -DGGML_VULKAN=ON when compiling. Note: the official Windows release of whisper.cpp does not include a Vulkan build.
2. Download a Whisper model; it can be installed directly in Claude Desktop using download_model. For English-only use, large-v3-turbo (GPU) or medium.en-q5_0 (CPU) is recommended; for multilingual use, large-v3-turbo or large-v3-turbo-q5_0 (CPU) is recommended. English-only models (*.en.bin) output [FOREIGN] on non-English audio and cannot be used for other languages.
3. Install FFmpeg (via winget or by downloading from ffmpeg.org and adding it to PATH).
4. Install this MCP server.
5. Configure Claude Desktop: open Settings → Developer → Edit Config and add a whisper entry. The config file is located at C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json, and double backslashes must be used in paths. After saving, fully restart Claude Desktop.
6. Verify the setup: in Claude Desktop, ask “Check your whisper config” and “Check your system hardware” to confirm that the GPU is detected and Vulkan acceleration is active.

After installation, you can directly say: “Transcribe C:\Users\Me\Downloads\meeting.mp3”, “Transcribe this folder of recordings and save each as a text file”, “Generate Japanese and English subtitles for this video”, “Start a batch transcription of everything in this folder”, “How long will it take to transcribe these files?”, “Check if GPU acceleration is working”, “Transcribe this file in privacy mode”.

GPU acceleration

The precompiled Vulkan release automatically enables GPU acceleration with no additional configuration required. It has been tested on an AMD Radeon RX Vega 56 (GCN 5th generation). Any GPU supporting Vulkan 1.0+ should work, including NVIDIA and Intel Arc. During transcription, GPU utilization is typically 15–20%, returning to idle between files. Supports WWindows 10 and Windows 11, no Windows 11-specific configuration required, the tool does not make Win32 API calls.

Multilingual Support

Whisper can automatically detect the spoken language and transcribe in that language. The built-in translation model only supports translation into English. For best multilingual accuracy, the large-v3 model is recommended. English-only models cannot detect or transcribe other languages. Example: when requesting subtitle generation, set language=auto and translate_to_english=true; Whisper detects the language and generates SRT or VTT in the native language, and a second pass generates the English translation. The SRT can be loaded in VLC via Subtitle → Add Subtitle File.

Privacy and Compliance

Audio and video never leave the local machine; this guarantee holds unconditionally. However, transcribed text is different—when returned inline in tool responses, it is processed through Claude's API. For regulated content (medical, legal, financial, enterprise), privacy mode can prevent text transmission. Privacy mode restricts all tool responses to metadata only (file name, word count, save path) and does not transmit any transcribed text to the Claude API. It can be enabled per call on any transcription tool via privacy_mode=true, or globally in the configuration via WHISPER_PRIVACY_MODE=true. Consent threshold: in standard mode, on first use per session, a full privacy disclosure is shown before any transcribed text is returned, requiring explicit confirmation. This can be skipped by setting WHISPER_CONSENT_ACKNOWLEDGED=true in the configuration. PRIVACY.md provides complete compliance guidance for HIPAA, GDPR, attorney-client privilege, FERPA, SOX, and PCI-DSS.

Security Features

• Input validation: all file and folder paths are validated before use, UNC paths and directory traversal sequences are rejected, files larger than 10 GB are rejected, and job_id and batch_id are checked against the server-generated format.
• Model download restrictions: downloads only from two trusted Hugging Face namespaces (ggerganov/whisper.cpp and ggml-org), arbitrary URLs are rejected, and redirects are validated against an allowlist. SHA256 digest verification has not yet been performed for every model.
• Model selection sandbox: switch_model and transcribe_audio model overrides only accept .bin files within the configured model directory.
• No PATH hijacking: system binaries invoked by the server (tasklist, wmic) are invoked via absolute System32 paths.

Use Cases

• Transcribe meeting recordings and save them as text.
• Batch transcribe recording files in a folder.
• Generate Japanese and English subtitles for videos.
• Process transcriptions of sensitive or regulated content locally.
• Designed for free-tier users, the tool minimizes Claude API interactions; heavy work such as scanning, analysis, queuing, running, and verification is done locally.

Limitations

• Only works on Windows 10/11.
• Requires Node.js 18+, the whisper.cpp Vulkan binary, Whisper model files, and FFmpeg (for video and non-WAV/MP3 audio).
• The official whisper.cpp Windows release does not include a Vulkan build.
• Built-in translation only supports English.
• Some operations are rejected while the model server is running.
• A resident model occupies VRAM.
• Model downloads have not yet been verified with SHA256.

License

Non-commercial use: MIT, free for personal, educational, and non-commercial use. Commercial use: requires a separate commercial license (see COMMERCIAL-LICENSE.md). Pull Requests are welcome.