用途
whisper-windows-mcp 是一个 Windows 原生的 MCP（Model Context Protocol）服务器，让 Claude Desktop 能够在本地使用 whisper.cpp 转写音频和视频文件。该项目专为 Windows 用户编写，因为流行的 whisper-mcp 包是为 macOS 和 Unix 环境构建的，无法在 Windows 上使用。所有转写均在本地运行，音频、视频或文件路径不会离开你的机器。
主要能力
- 单文件转写，支持阻塞（默认）或后台模式，适合长文件。
- 输出格式：timestamps（带时间戳的分段，默认）、text（纯文本）、json（仅阻塞模式）、srt（SubRip 字幕）、vtt（WebVTT 字幕）、lrc（歌词/卡拉 OK 格式）、csv（带时间戳）。字幕与 CSV 文件保存在源文件旁。
- 后台任务监控：返回已用时间、最后处理时间戳以及完成后的完整转写文本。
- 批量转写：自动按文件时长排序（最短优先），逐个作为后台任务处理，每个完成后自动推进，无需轮询。
- 交互式批量转写：逐个处理，每个文件前有预览与确认。
- 字幕生成：支持自动语言检测和英文翻译输出，生成 SRT 或 WebVTT。当同时请求原生语言和翻译时，保存两个文件：filename.ja.srt（原语言）和 filename.en.srt（英文翻译）。Whisper 内置翻译仅支持翻译为英文。
- 文件分析：在转写前返回时长、大小、编解码器以及 CPU 和 GPU 的预估转写时间。对文件夹显示可排序表格及转写状态。
- 配置验证：检查 whisper-cli.exe、模型文件和 FFmpeg 是否可访问。
- 模型管理：列出已安装模型（文件名、大小、是否激活、量化状态、推荐用例），从 Hugging Face 下载模型（仅限可信命名空间），在当前会话中切换激活模型（重启后不保留，需在配置中修改 WHISPER_MODEL 才能永久生效）。
- GPU 检测：报告 GPU 名称、显存、ggml-vulkan.dll 是否存在，并推荐适合硬件的模型大小。
- 持久模型服务器：启动 whisper-server 使激活模型常驻显存，所有转写通过 localhost 提供服务，避免每次重新加载模型。注意：常驻模型会在服务器整个生命周期占用显存，需显式启动和停止。服务器仅绑定 127.0.0.1，不暴露网络。服务器运行时，需要一次性 CLI 的操作（后台任务、start_batch、generate_subtitles、lrc/csv 输出以及 HTTP API 不支持的高级选项如 beam_size、best_of、word_timestamps、diarize 等）会被拒绝并提示先停止服务器。
使用方式
前置要求：Node.js 18 或更高版本；带 Vulkan GPU 支持的 whisper.cpp 二进制（预编译 Vulkan 发布版或从源码构建）；一个 Whisper 模型文件；视频文件和非 WAV/MP3 音频需要 FFmpeg。
步骤：
- 安装 whisper.cpp 二进制。推荐从 releases 页面下载 whisper-vulkan-win-x64.zip，解压到 C:\whisper\Release\。这是启用 Vulkan GPU 加速的自编译版本，适用于 AMD、NVIDIA 和 Intel GPU，无需厂商特定 SDK。也可从源码构建（需要 Git、CMake、Visual Studio Build Tools 2022+ 和 Vulkan SDK），编译时使用 -DGGML_VULKAN=ON。注意：whisper.cpp 官方 Windows 发布版不包含 Vulkan 构建。
- 下载 Whisper 模型，可在 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]，不能用于其他语言。
- 安装 FFmpeg（winget 或从 ffmpeg.org 下载并加入 PATH）。
- 安装此 MCP 服务器。
- 配置 Claude Desktop：打开设置 → Developer → Edit Config，添加 whisper 条目。配置文件位于 C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json，路径中需使用双反斜杠。保存后完全重启 Claude Desktop。
- 验证设置：在 Claude Desktop 中询问“Check your whisper config”和“Check your system hardware”，确认 GPU 被检测且 Vulkan 加速已激活。
安装后可以直接说：“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 加速
预编译 Vulkan 发布版自动启用 GPU 加速，无需额外配置。已在 AMD Radeon RX Vega 56（GCN 第五代）上测试。任何支持 Vulkan 1.0+ 的 GPU 都应可用，包括 NVIDIA 和 Intel Arc。转写期间 GPU 利用率通常为 15–20%，文件之间回到空闲。支持 Windows 10 和 Windows 11，无需 Windows 11 特定配置，工具不进行 Win32 API 调用。
多语言支持
Whisper 可自动检测口语语言并以该语言转写。内置翻译模型仅支持翻译为英文。最佳多语言准确性建议使用 large-v3 模型。仅英文模型无法检测或转写其他语言。示例：请求生成字幕时设置 language=auto 和 translate_to_english=true，Whisper 检测语言并生成原生语言 SRT 或 VTT，第二遍生成英文翻译。可在 VLC 中通过 Subtitle → Add Subtitle File 加载 SRT。
隐私与合规
音频和视频绝不离开本机，此保证无条件成立。但转写文本不同——当在工具响应中内联返回时，会经过 Claude 的 API 处理。对于受监管内容（医疗、法律、金融、企业），隐私模式可阻止文本传输。隐私模式将所有工具响应限制为仅元数据（文件名、字数、保存路径），不向 Claude API 传输任何转写文本。可在任意转写工具上通过 privacy_mode=true 按次启用，或在配置中通过 WHISPER_PRIVACY_MODE=true 全局启用。同意门槛：标准模式下每会话首次使用时，在返回任何转写文本前显示完整隐私披露，需明确确认。可在配置中设置 WHISPER_CONSENT_ACKNOWLEDGED=true 跳过。PRIVACY.md 提供 HIPAA、GDPR、律师-客户特权、FERPA、SOX、PCI-DSS 的完整合规指导。
安全特性
- 输入验证：所有文件和文件夹路径在使用前验证，拒绝 UNC 路径和目录遍历序列，拒绝超过 10 GB 的文件，job_id 和 batch_id 按服务器生成格式检查。
- 模型下载限制：仅从两个可信 Hugging Face 命名空间（ggerganov/whisper.cpp 和 ggml-org）下载，拒绝任意 URL，重定向根据允许列表验证。尚未对每个模型进行 SHA256 摘要验证。
- 模型选择沙箱：switch_model 和 transcribe_audio 的模型覆盖仅接受配置模型目录内的 .bin 文件。
- 无 PATH 劫持：服务器调用的系统二进制（tasklist、wmic）通过 System32 绝对路径调用。
适用场景
- 转写会议录音并保存为文本。
- 批量转写文件夹中的录音文件。
- 为视频生成日文和英文字幕。
- 在本地处理敏感或受监管内容的转写。
- 为免费层级用户设计，工具尽量减少 Claude API 交互，扫描、分析、排队、运行、验证等重活均在本地完成。
限制
- 仅适用于 Windows 10/11。
- 需要 Node.js 18+、whisper.cpp Vulkan 二进制、Whisper 模型文件和 FFmpeg（视频及非 WAV/MP3 音频）。
- whisper.cpp 官方 Windows 发布版不包含 Vulkan 构建。
- 内置翻译仅支持英文。
- 模型服务器运行时部分操作会被拒绝。
- 常驻模型占用显存。
- 模型下载尚未验证 SHA256。
许可
非商业使用：MIT，个人、教育和非商业用途免费。商业使用：需要单独的商业许可（见 COMMERCIAL-LICENSE.md）。欢迎 Pull Request。
