# eviscerations/whisper-windows-mcp [Health: Active]

**Category:** 🎙️ Speech-to-Text  
**Repository:** https://github.com/eviscerations/whisper-windows-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 502  
**Views:** 20  
**Installs:** 2  
**Upvotes:** 1  
**Directory Page:** https://allmcps.com/mcp/eviscerations-whisper-windows-mcp

## Description
Windows-native local audio and video transcription using whisper.cpp with Vulkan GPU acceleration. No cloud APIs, no Python. Batch processing, multilingual support, model management, and background job handling built in.

## Tools
Capabilities this server exposes over MCP:

- **transcribe_audio** — Transcribe a single file. Supports blocking (default) or background mode for long files.
- **check_progress** — Monitor a background transcription job started with `transcribe_audio` (background=true).
- **start_batch** — Automated sequential batch transcription of all untranscribed files in a folder. Sorts by duration (shortest first), processes one at a time as background jobs, validates each output. Batch self-advances when each file finishes — no polling required.
- **check_batch_progress** — Monitor a running batch. Automatically advances to the next file when the current one finishes. Returns overall progress, current file with timestamp, and any failed files.
- **generate_subtitles** — Generate subtitle files. Supports automatic language detection and English translation output. Outputs SRT (widest compatibility) or WebVTT (web and HTML5 video).
- **analyze_media** — Analyze files before committing to transcription. Returns duration, size, codec, and estimated transcription time on CPU and GPU. For folders, shows all files in a sortable table with transcription status.
- **check_config** — Verify whisper-cli.exe, the model file, and FFmpeg are all accessible. Run this first if anything is failing.
- **list_models** — List all Whisper model files installed in your models directory. Shows filename, size, whether it is currently active, quantization status, and recommended use case. No network calls — reads local filesystem only.
- **download_model** — Download a Whisper model directly from Hugging Face into your models directory. Only downloads from trusted Hugging Face namespaces. After downloading, use `switch_model` to activate it.
- **switch_model** — Switch the active Whisper model for the current session without restarting Claude Desktop. Change is session-scoped — does not persist after restart. To make permanent, update `WHISPER_MODEL` in your config.
- **check_system** — Detect GPU hardware and verify Vulkan acceleration is available. Reports GPU name, VRAM, whether `ggml-vulkan.dll` is present, and recommends the best model size for your hardware.
- **whisper_server** — Start, stop, or check the **persistent model server** (whisper.cpp's `whisper-server`). While running, the active model stays resident in VRAM and every `transcribe_audio` / `transcribe_batch` call is served over localhost with **no per-file model reload** — a large speedup when transcribing many s…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "whisper-windows-mcp": {
    "command": "npx",
    "args": ["-y","whisper-windows-mcp"],
    "env": {
      "WHISPER_CLI_PATH": "",
      "WHISPER_MODEL": ""
    }
  }
}
```

**Requires environment variables:** `WHISPER_CLI_PATH`, `WHISPER_MODEL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What eviscerations/whisper-windows-mcp MCP server does

The eviscerations/whisper-windows-mcp MCP server connects Claude Desktop to a local Windows transcription workflow based on whisper.cpp. It can process individual audio or video files, return timestamped or plain text output, and save supported output formats beside the source media. Supported formats include text, JSON in blocking mode, SRT, WebVTT, LRC, and CSV.

The server also handles longer-running work. A single transcription can run as a background job and be checked later, while folder batches process untranscribed files sequentially. Batch processing orders files by duration, validates outputs, and advances to the next file when the current one finishes. Subtitle generation supports language detection, English translation output, SRT, and WebVTT.

## How it works

Claude Desktop sends MCP tool calls to the locally installed Node.js server. The server invokes a Windows whisper.cpp executable and uses a configured Whisper model. Vulkan-enabled binaries can use AMD, NVIDIA, or Intel GPUs without a vendor-specific SDK; CPU processing is also supported through suitable models and configuration.

Before transcription, `analyze_media` can report file duration, size, codec, estimated CPU and GPU time, and folder-level transcription status. `check_config` verifies access to the whisper executable, model, and FFmpeg. `check_system` inspects GPU hardware, VRAM, and Vulkan support. A persistent whisper.cpp model server can keep the active model resident in VRAM for repeated transcription requests.

## Setup and configuration

The eviscerations/whisper-windows-mcp MCP server requires Node.js 18 or later, whisper.cpp binaries, a Whisper model, and FFmpeg for video and non-WAV/MP3 audio. The project documents a prebuilt Vulkan Windows release or a source build using CMake, Visual Studio Build Tools, and the Vulkan SDK. The executable and supporting DLLs are expected in a local Windows directory.

Install the Node package with `npm install -g whisper-windows-mcp`. Claude Desktop can launch it with `npx -y whisper-windows-mcp`. Its MCP configuration must provide `WHISPER_CLI_PATH` and `WHISPER_MODEL`, pointing to the local whisper.cpp executable and model file. Windows paths in the JSON configuration require escaped backslashes. Restart Claude Desktop after saving the configuration, then run the configuration and hardware checks.

Models can be listed and downloaded through the MCP tools. Downloads come from trusted Hugging Face namespaces and are placed in the configured models directory. `switch_model` changes the active model for the current session; changing the `WHISPER_MODEL` setting is required for a persistent default.

## Tools and capabilities

Available capabilities include:

- Transcribe one file with language selection, timestamps, output formats, prompts, sampling controls, offsets, duration limits, word timestamps, and optional speaker-related processing.
- Start and monitor background transcription jobs.
- Run sequential folder batches and inspect overall progress or failed files.
- Generate SRT or WebVTT subtitles, including English translations.
- Inspect media metadata and estimate processing time.
- Check configuration, GPU/Vulkan availability, installed models, and recommended model sizing.
- Download models from Hugging Face and switch the active model.
- Start, stop, or inspect the persistent whisper.cpp model server.

## Limitations and notes

The eviscerations/whisper-windows-mcp MCP server is Windows-focused and depends on external whisper.cpp binaries. FFmpeg is required for video and for audio formats outside native WAV/MP3 handling. English-only model files cannot transcribe other languages and produce `[FOREIGN]` on non-English audio; multilingual models are needed for other languages.

GPU acceleration depends on Vulkan-capable hardware and the required Vulkan DLL. Model choice affects speed, memory use, and accuracy. Session-level model switching does not survive a restart. Stereo diarization requires speakers on separate channels, while mono speaker-turn detection requires a compatible tdrz model. Background jobs should be monitored with their returned job IDs, although batches advance without polling.

_Full upstream README: https://allmcps.com/mcp/eviscerations-whisper-windows-mcp/readme_