whisper-windows-mcp

# whisper-windows-mcp [](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml) [](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp) 一款适用于Windows的本地MCP（模型上下文协议）服务器，允许Claude Desktop在本地使用[whisper.cpp](https://github.com/ggml-org/whisper.cpp)转录音频和视频文件——支持GPU加速、多语言支持和批量处理。所有转录操作都在本地进行——绝不会离开您的机器。 > **为什么存在这个项目？** > 流行的`whisper-mcp`软件包是为macOS构建的，并假设Unix环境。它在Windows上无法正常工作。这个软件包是专门为希望在Windows上集成本地AI转录功能的Claude Desktop用户编写的。 --- ## 您可以用它做什么 安装后，您可以直接在Claude Desktop中执行以下操作： - *"转录 C:\Users\Me\Downloads\meeting.mp3"* - *"转录此文件夹中的录音并将其保存为文本文件"* - *"为此视频生成日语和英语字幕"* - *"开始批量转录此文件夹中的所有内容"* - *"转录这些文件需要多长时间？"* - *"检查GPU加速是否正常工作"* - *"以隐私模式转录此文件"* --- ## 要求 1. **Node.js 18 或更高版本** — [nodejs.org](https://nodejs.org) 2. **带有Vulkan GPU支持的whisper.cpp二进制文件** — 请参见步骤 1 3. **Whisper模型文件** — 请参见步骤 2 4. **FFmpeg** — 视频文件和非WAV/MP3音频文件所需 --- ## 步骤 1 — 安装whisper.cpp二进制文件 ### 选项 A — 预构建的Vulkan版本（推荐） 从[发布页面](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)下载`whisper-vulkan-win-x64.zip`。 这是启用了**Vulkan GPU加速**的自定义编译版本。与AMD、NVIDIA和Intel GPU兼容——无需特定于供应商的SDK。 解压到 `C:\whisper\Release\`。您应该最终得到： ``` 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 ``` GPU加速是自动的——无需额外配置。 ### 选项 B — 从源代码构建 需要：Git、CMake、Visual Studio Build Tools 2022+，并启用“C++桌面开发”，以及来自[lunarg.com](https://vulkan.lunarg.com/sdk/home#windows)的Vulkan SDK。 ``` 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 ``` 将二进制文件从`build\bin\Release\`复制到`C:\whisper\Release\`。 > **注意：** GitHub上的官方whisper.cpp Windows版本不包括Vulkan构建。您必须使用上述预构建版本或使用`-DGGML_VULKAN=ON`编译源代码。 --- ## 步骤 2 — 下载Whisper模型 | 模型 | 大小 | 速度 | 精度 | 最适合 | |---|---|---|---|---| | `ggml-tiny.en.bin` | 75 MB | 非常快 | 基本 | 快速测试 | | `ggml-base.en.bin` | 142 MB | 快 | 良好 | 日常英语 | | `ggml-small.en.bin` | 466 MB | 中等 | 更好 | 重要录音 | | `ggml-medium.en.bin` | 1.5 GB | GPU上快速 | 非常好 | 英语最佳质量 | | `ggml-large-v3-turbo.bin` | 1.6 GB | GPU上快速 | 优秀 | **推荐用于英语GPU批量工作 - 比large-v3快约6倍，精度损失最小** | | `ggml-large-v3.bin` | 2.9 GB | GPU上快速 | 优秀 | 多语言，最大精度 | | `ggml-medium.en-q5_0.bin` | 514 MB | 快 | 非常好 | **最佳CPU-only英语选项 - 低内存下精度高** | | `ggml-large-v3-turbo-q5_0.bin` | 547 MB | 快 | 优秀 | **最佳CPU-only多语言选项** | | `ggml-large-v3-q5_0.bin` | 1.1 GB | CPU上中等 | 优秀 | 多语言，CPU友好 | 使用Claude Desktop中的`download_model`直接安装任意一个模型。对于**仅限英语**的使用：`large-v3-turbo`（GPU）或`medium.en-q5_0`（CPU）是最佳起点。对于**多语言**的使用：`large-v3-turbo`或`large-v3-turbo-q5_0`（CPU）。仅限英语的模型（`*.en.bin`）在非英语音频上输出`[FOREIGN]`，不能用于其他语言。 --- ## 步骤 3 — 安装FFmpeg FFmpeg是视频文件和非原生音频格式所需的。 通过winget安装： ``` winget install ffmpeg ``` 或从[ffmpeg.org](https://ffmpeg.org/download.html)下载并添加到您的PATH中。 验证： ``` ffmpeg -version ``` --- ## 步骤 4 — 安装此MCP服务器 ``` npm install -g whisper-windows-mcp ``` --- ## 步骤 5 — 配置Claude Desktop 打开Claude Desktop → 设置 → 开发者 → 编辑配置。 添加`whisper`条目： ```json { "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" } } } } ``` 配置文件位置：`C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json` > 在所有路径中使用**双反斜杠**。 保存并**完全重启**Claude Desktop。您应该在设置 → 开发者中看到带有绿色运行徽章的`whisper`。 --- ## 步骤 6 — 验证您的设置 在Claude Desktop中，询问： > *"检查您的whisper配置"* 然后： > *"检查您的系统硬件"* 这确认您的GPU被检测到并且Vulkan加速处于活动状态。 --- ## 可用工具 ### `transcribe_audio` 转录单个文件。支持阻塞（默认）或后台模式用于长文件。 | 参数 | 描述 | |---|---| | `file_path` | 文件的绝对路径（必填） | | `language` | 语言代码（`en`、`ja`、`es`等）或`auto`进行检测。默认：`en` | | `output_format` | `timestamps`（默认）、`text`、`json`、`srt`、`vtt`、`lrc`或`csv` | | `save_to_file` | 将转录文本保存为.txt文件，位于源文件旁边 | | `background` | 以分离的作业运行 - 立即返回作业ID。使用`check_progress`进行监视。建议用于10分钟以上的长文件。 | | `privacy_mode` | 为此调用覆盖隐私模式。`true` = 仅元数据，无转录文本传输。`false` = 即使全局设置`WHISPER_PRIVACY_MODE=true`，也返回文本。省略则使用全局设置。 | | `threads` | CPU线程覆盖 | | `temperature` | 采样温度0.0-1.0。默认0.0（确定性）。 | | `prompt` | 先前上下文字符串 - 提高特定领域词汇或说话者名称的准确性。例如：`"Names: Keemstar, DramaAlert."` | | `condition_on_prev_text` | 在段落之间重新启用上下文条件。默认false。 | | `beam_size` | 梁搜索宽度。越高 = 更准确，但更慢。默认5。 | | `best_of` | 评估的候选序列。默认5。 | | `gpu_device` | 多GPU系统上的GPU设备索引。默认0。 | | `processors` | 并行处理器数量。默认1。 | | `word_timestamps` | 每个单词的时间戳段。有助于剪辑对齐。 | | `max_segment_length` | 最大段长度（字符）。 | | `diarize` | 立体声说话者识别 - 需要立体声音频，扬声器在单独的通道上。 | | `tinydiarize` | 单声道说话者转折检测 - 在单通道音频上标记`[SPEAKER_TURN]`。需要tdrz模型：`download_model small.en-tdrz`，然后`switch_model ggml-small.en-tdrz.bin`。 | | `vad_model` | Silero VAD模型.bin的路径。从音频开始剥离沉默 - 减少嘈杂文件的幻觉。 | | `offset_t` | 毫秒偏移量。 | | `duration` | 从偏移量开始的处理持续时间（毫秒）。 | **输出格式：** - `timestamps` - 带时间戳的段落，例如`[00:00:01.230 --> 00:00:04.560] Hello world`（默认） - `text` - 纯文本，无时间代码 - `json` - 结构化JSON（仅阻塞模式） - `srt` - SubRip字幕文件，保存在源文件旁边 - `vtt` - WebVTT字幕文件，保存在源文件旁边 - `lrc` - LRC歌词/卡拉OK格式，保存在源文件旁边 - `csv` - 带时间戳的CSV，保存在源文件旁边 --- ### `check_progress` 监视使用`transcribe_audio`（background=true）启动的后台转录作业。 返回已用时间、最后一个处理的时间戳以及完成后完整的转录文本。 | 参数 | 描述 | |---|---| | `job_id` | `transcribe_audio`返回的作业ID | | `privacy_mode` | 为此检查覆盖隐私模式。`true` = 仅元数据，无论作业如何启动。 | --- ### `start_batch` 自动顺序批量转录文件夹中所有未转录的文件。按时长排序（最短优先），一次处理一个文件作为后台作业，并在每个文件完成后进行验证。批处理在每个文件完成后自动推进 - 无需轮询。 | 参数 | 描述 | |---|---| | `folder_path` | 文件夹路径（必填） | | `language` | 语言代码。默认：`en` | | `threads` | CPU线程覆盖 | | `output_format` | `timestamps`（默认）或`text` | | `privacy_mode` | 覆盖隐私模式。批处理开始前需要一次确认；所有文件然后无人值守地处理。不会返回转录文本。 | --- ### `check_batch_progress` 监视正在运行的批处理。自动推进到下一个文件，当当前文件完成后。返回整体进度、当前文件的时间戳以及任何失败的文件。 | 参数 | 描述 | |---|---| | `batch_id` | `start_batch`返回的批处理ID | --- ### `transcribe_batch`（交互式） 一次处理文件，预览并确认每个文件前。适用于您希望一边查看一边处理的情况。 | 参数 | 描述 | |---|---| | `folder_path` | 文件夹路径（必填） | | `file_index` | 要处理的文件（基于1的）。省略以先列出文件。 | | `language` | 语言代码。默认：`en` | | `recursive` | 包括子文件夹 | | `output_format` | `timestamps`（默认）或`text` | | `privacy_mode` | 覆盖隐私模式。每个文件前需要确认；仅返回元数据。 | --- ### `generate_subtitles` 生成字幕文件。支持自动语言检测和英语翻译输出。输出SRT（兼容性最广）或WebVTT（网页和HTML5视频）。 | 参数 | 描述 | |---|---| | `file_path` | 文件路径（必填） | | `language` | 语言代码或`auto`进行检测。默认：`en` | | `output_format` | `srt`（默认）或`vtt` | | `translate_to_english` | 还生成英语翻译字幕文件。仅当源语言不是英语时适用。 | | `background` | 以分离的后台作业运行。返回作业ID以供`check_progress`使用。 | | `threads` | CPU线程覆盖 | 当请求原生和翻译时，会在源文件旁边保存两个文件： - `filename.ja.srt` - 原始语言 - `filename.en.srt` - 英语翻译 > Whisper的内置翻译仅翻译 **至英语**。对于其他目标语言，请单独翻译字幕文件内容。 --- ### `analyze_media` 分析文件后再进行转录。返回时长、大小、编解码器以及CPU和GPU的预计转录时间。对于文件夹，显示所有文件可排序的表格，转录状态。 | 参数 | 描述 | |---|---| | `path` | 单个文件或文件夹的路径（必填） | | `sort_by` | 文件夹：`duration`（默认）、`name`或`size` | --- ### `check_config` 验证whisper-cli.exe、模型文件和FFmpeg是否都可访问。如果任何一项都失败，请先运行此命令。 --- ### `list_models` 列出您模型目录中安装的所有Whisper模型文件。显示文件名、大小、当前活动状态、量化状态和推荐使用场景。无需网络调用 - 只读本地文件系统。 --- ### `download_model` 直接从Hugging Face下载Whisper模型到您的模型目录。仅从受信任的Hugging Face命名空间下载。下载后，使用`switch_model`激活它。 | 参数 | 描述 | |---|---| | `model_name` | 要下载的模型名称，例如`large-v3-turbo`、`large-v3-turbo-q5_0`、`medium.en-q5_0` | --- ### `switch_model` 在不重启Claude Desktop的情况下切换当前的Whisper模型。更改是会话范围的 - 重启后不持久化。要永久更改，请更新您的配置中的`WHISPER_MODEL`。 | 参数 | 描述 | |---|---| | `model_name` | 模型文件名（例如`ggml-large-v3-turbo.bin`）或完整路径。必须是`.bin`文件，位于配置的模型目录中。 | --- ### `check_system` 检测GPU硬件并验证Vulkan加速是否可用。报告GPU名称、VRAM、`ggml-vulkan.dll`是否存在，并推荐适合您硬件的最佳模型大小。 --- ### `whisper_server` 启动、停止或检查**持久模型服务器**（whisper.cpp的`whisper-server`）。运行期间，活动模型驻留在VRAM中，每个`transcribe_audio`/`transcribe_batch`调用都通过localhost服务，并**不会重新加载每个文件的模型** - 在转录许多短文件时，这是一大速度提升，其中一次性模型加载成本否则占主导地位。 | 参数 | 描述 | |---|---| | `action` | `start` - 使用活动模型启动；`stop` - 关闭并释放VRAM；`status` - 报告运行状态、驻留模型、端口和运行时间。 | - ⚠️ **驻留模型占用GPU VRAM。** 启动时有意启动，完成工作后`stop`以将GPU返回给其他应用程序共享卡。停止时执行完整的kill，因此VRAM实际上被释放。 - `switch_model`在服务器运行时热交换驻留模型（无需重启）。 - 绑定到`127.0.0.1` - 从未在网络上暴露。 - 而服务器开启，需要一次性CLI的作业 - 后台作业、`start_batch`、`generate_subtitles`、`lrc`/`csv`输出以及高级调用选项HTTP API不支持（`beam_size`、`best_of`、`word_timestamps`、`diarize`、`tinydiarize`、`vad_model`、`offset_t```` `beam_size`、`best_of`、`word_timestamps`、`diarize`、`tinydiarize`、`vad_model`、`offset_t`）- 被**拒绝**，并提示“请先停止服务器” - 而不是静默忽略，因此永远不会有两个引擎争夺GPU。 --- ## 支持的格式 | 类型 | 格式 | |---|---| | 原生（无需转换） | `mp3`、`wav` | | 视频（通过FFmpeg自动转换） | `mp4`、`mkv`、`avi`、`mov`、`webm`、`flv`、`wmv`、`m4v`、`ts`、`3gp` | | 音频（通过FFmpeg自动转换） | `m4a`、`ogg`、`flac` | --- ## GPU加速 预构建的Vulkan版本自动启用GPU加速。在AMD Radeon RX Vega 56（GCN 5代）上测试。任何支持Vulkan 1.0+的GPU都应工作，包括NVIDIA和Intel Arc。 **性能比较（large-v3模型，~14分钟音频文件）：** | 硬件 | 时间 | |---|---| | CPU仅限（Ryzen 7 2700x，8线程） | ~22分钟（估计） | | GPU（Vega 56 via Vulkan） | ~3m 22s | 转录期间GPU利用率通常为15-20%，在文件之间降至空闲。 支持Windows 时间10和Windows 11。无需Windows 11特定配置 - 该工具不调用Win32 API，在两个操作系统上均可运行。 --- ## 多语言支持 Whisper可以自动检测口语语言并以该语言转录。内置翻译模型仅翻译 **至英语**。 为了获得最佳多语言准确性，请使用`large-v3`模型。英语特定模型（`*.en.bin`）无法检测或转录其他语言。 **示例 - 外语视频带字幕：** 1. 询问Claude生成字幕，`language=auto`和`translate_to_english=true` 2. Whisper检测语言并生成原生语言SRT或VTT 3. 第二次传递生成英语翻译 4. 在VLC中通过字幕->添加字幕文件加载SRT，或在任何网页播放器中使用VTT --- ## 隐私和合规 whisper-windows-mcp包含内置的隐私架构，用于处理敏感和受监管的内容。 **音频和视频永远不会离开您的机器。** 该保证是无条件的。 **转录文本**则不同 - 当内联返回工具响应时，它会由Claude的API处理。对于大多数用户来说，这是预期的行为。对于受监管的内容（医疗、法律、财务、公司），隐私模式可防止这种情况发生。 **隐私模式**限制所有工具响应仅限元数据。不会在任何情况下将转录文本传输到Claude的API。启用每个调用`privacy_mode=true`，或通过`WHISPER_PRIVACY_MODE=true`在您的配置中全局启用。 **同意门控** - 在标准模式下首次使用每个会话时，会显示完整的隐私披露，然后再返回任何转录文本。您必须显式确认，然后继续。设置`WHISPER_CONSENT_ACKNOWLEDGED=true`在您的配置中跳过此操作。 参见[PRIVACY.md](PRIVACY.md)获取完整的合规指南（HIPAA，GDPR，律师-客户特权，FERPA，SOX，PCI-DSS）。 --- ## 设计用于免费层用户 此工具旨在尽量减少Claude API交互。整个转录工作流程 - 扫描，分析，排队，运行，验证 - 设计为需要尽可能少的Claude交互。繁重的工作在您的本地机器上进行。 --- ## 可选环境变量 | 变量名 | 描述 | |---|---| | `WHISPER_CLI_PATH` | whisper-cli.exe 的路径（必填） | | `WHISPER_MODEL` | 模型 .bin 文件的路径（必填） | | `WHISPER_THREADS` | CPU 线程数覆盖 | | `WHISPER_GPU_DEVICE` | 用于多 GPU 系统的 Vulkan 设备索引，用于转录（Vulkan 枚举索引 - 请查看 whisper-cli 的启动日志；不是 Windows GPU 顺序）。可以通过 `gpu_device` 在每次调用时覆盖。请参阅 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)。 | | `WHISPER_FOREGROUND_MAX_SEC` | 前台转录的截止时间（秒，默认 210）。估计运行时间较长的任务将改为后台模式，以避免 Claude Desktop 的 ~4 分钟工具超时。 | | `FFMPEG_PATH` | 如果 FFmpeg 未在系统 PATH 中，则需要指定其路径 | | `WHISPER_SERVER_PATH` | 用于持续模型服务器的 `whisper-server.exe` 的路径（默认：与 `whisper-cli.exe` 相同）。请参阅 `whisper_server` 工具。 | | `WHISPER_SERVER_PORT` | 持续模型服务器的本地端口（默认 8571）。始终绑定到 `127.0.0.1`。 | | `WHISPER_PRIVACY_MODE` | 当为 `true` 时，所有工具响应仅返回元数据 - 不会将转录文本传输到 Claude 的 API。适用于受监管或机密内容。可以通过 `privacy_mode` 参数在每次调用时覆盖。请参阅 [PRIVACY.md](PRIVACY.md)。 | | `WHISPER_CONSENT_ACKNOWLEDGED` | 当为 `true` 时，将跳过在返回转录文本之前显示的一次性会话同意披露。当您理解隐私边界并且不再需要提醒时，请设置此变量。在隐私模式激活时，此变量无效。 | --- ## 安全 **二进制验证。** 要验证预构建版本中 whisper-cli.exe 二进制文件的完整性，请在 PowerShell 中检查其 SHA256 哈希值： ```powershell Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256 ``` v1.4.0 版本二进制文件的预期哈希值在 [发布页面](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) 中有文档记录。 **输入验证。** 所有文件和文件夹路径在每次使用时都会被验证，对于每个接受路径的工具 - UNC 路径 (`\\server\share`) 和目录遍历序列 (`..`) 都会被拒绝。大于 10 GB 的文件将被拒绝，以防止资源耗尽。`job_id` 和 `batch_id` 在用于构建任何文件路径之前，将根据服务器生成的确切格式进行检查，以防止通过构造 ID 遍历到作业目录之外。 **转录注入意识。** 音频文件可能包含口语内容，转录后类似于指令。Claude 的内置防御机制可以处理这一点，但值得注意的是，转录内容被 MCP 服务器本身视为数据 - 永远不会作为指令。由于转录内容仍可以影响 Claude 调用下一个工具，因此路径/ID 验证被防御性地应用，而不是仅依赖单用户假设。 **模型下载受限制。** `download_model` 工具仅从两个受信任的 Hugging Face 命名空间 (`ggerganov/whisper.cpp` 和 `ggml-org`) 下载。拒绝任意 URL。在跟随重定向之前，会根据允许列表验证重定向。（目前尚未针对每个模型的 SHA256 摘要进行验证 - 请参阅 SECURITY.md。） **模型选择被沙盒化。** `switch_model` 和 `transcribe_audio` 的 `model` 覆盖仅接受配置的模型目录内的 `.bin` 文件。通过规范化路径包含检查，该目录外的路径将被拒绝。 **没有 PATH 遮蔽。** 服务器代表您调用的系统二进制文件（`tasklist`、`wmic`）通过绝对 `System32` 路径调用，因此不能被 `PATH` 中较早的同名可执行文件遮蔽。 请参阅 [SECURITY.md](SECURITY.md) 以获取完整的安全策略。 --- ## 故障排除 请参阅 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 以获取详细的解决方案。如果您处理受监管的内容，请参阅 [PRIVACY.md](PRIVACY.md) 以获取合规性指南。 快速检查清单： - 配置中的路径使用 **双反斜杠** (`C:\\whisper\\...`) - `whisper-cli.exe` 存在于配置的路径中 - 模型 `.bin` 文件存在于配置的路径中 - FFmpeg 已安装并在 PATH 中（`ffmpeg -version` 工作） - 在编辑配置后，Claude Desktop 已完全重启 - Whisper 在设置 → 开发人员中显示为 **运行中** --- ## 许可证 **非商业用途：** MIT - 免费用于个人、教育和非商业用途。请参阅 [LICENSE](LICENSE)。 **商业用途：** 需要单独的商业许可证才能用于任何企业、专业或创收用途。请参阅 [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) 以获取条款和联系信息。 ## 贡献 欢迎拉取请求。请参阅 [ROADMAP.md](ROADMAP.md) 以获取计划功能。 如果您已经在上述未列出的硬件上测试了 GPU 加速，请通过问题报告您的结果 - GPU 型号、VRAM、模型大小和观察到的吞吐量。