Local Whisper

为 Claude 提供私密、本地的音频转录。Local Whisper 是一个模型上下文协议（MCP）服务，可在你自己的电脑上使用 Whisper 转录音频文件，因此语音备忘录、会议和讲座内容都不会离开你的电脑。它适用于 Claude Desktop、Claude Code，以及在你电脑上运行的 claude.ai 聊天。

https://github.com/user-attachments/assets/dc71b178-b60d-457e-8f33-732696671c02

功能

• 无需额外软件即可转录 WAV、Ogg Opus（WhatsApp 和 Telegram 语音消息）和 MP3 文件。将 ffmpeg 添加到 PATH 后，还可读取 M4A 和 FLAC 文件。
• 安装 ffmpeg 后，可转录 MP4 和 WebM 等视频文件：服务会提取音轨并忽略画面。无需先提取音频，即可将录制的会议或课程转换为文本或字幕。
• 在 Windows 和 Linux 上通过 Vulkan 使用 GPU，在 Apple Silicon 上通过 Metal 使用 GPU，并在需要时自动改用 CPU。使用默认模型 large-v3-turbo-q8_0 时，NVIDIA GeForce RTX 3080 转录一分钟音频约需一秒。
• 首次需要时下载模型，并根据 Hugging Face 发布的哈希值进行校验；闲置 5 分钟后释放内存，包括 GPU 内存。
• 返回纯文本、SubRip 字幕（SRT）或带时间戳的 JSON 片段。
• 对清晰录音使用语音活动检测跳过静音，确保时间戳准确；当背景噪声可能掩盖轻声语音时，则转录所有内容。
• 每个平台提供一个原生可执行文件：无需安装 Python 或 .NET 运行时。

安装

在下表中找到你的系统，并下载你使用 Claude 的应用对应的文件。 每个链接都会下载最新版本中的文件。

系统	Claude Desktop	Claude Code
Windows (x64)	下载 (.mcpb)	下载 (.zip)
搭载 Apple Silicon 的 macOS	下载 (.mcpb)	下载 (.tar.gz)
搭载 Intel 处理器的 macOS	下载 (.mcpb)	下载 (.tar.gz)
Linux (x64)	不可用	下载 (.tar.gz)
Linux (arm64)	不可用	下载 (.tar.gz)
任何系统：技能（可选）	下载 (.zip)	安装插件

技能会告诉 Claude 何时以及如何使用该服务。更多信息，请参阅 技能。

要查看你的 Mac 型号，请选择 Apple 菜单 > 关于本机。如果 芯片 一栏以 Apple 开头（例如 Apple M2），说明你使用的是 Apple Silicon。如果 处理器 一栏显示 Intel，则说明你使用的是 Intel 处理器。

要验证下载文件，请将其 SHA-256 哈希值与 发布页面上的 SHA256SUMS.txt 中的值进行比较。

Claude Desktop

要将 Local Whisper 添加到 Claude Desktop，请安装其扩展：

1. 从 安装表格中下载适用于你系统的扩展。
2. 打开文件。Claude Desktop 会显示扩展的详细信息。
3. 点击 安装。
4. 可选：在扩展设置中，选择存放音频的文件夹、模型和语言。

Claude Code

要将 Local Whisper 添加到 Claude Code，请将可执行文件注册为 MCP 服务：

1. 从 安装表格中下载适用于你系统的压缩包，并将其解压到一个固定保留的文件夹中。

2. 运行以下命令：

   claude mcp add local-whisper -- PATH_TO_EXECUTABLE
   

   将 PATH_TO_EXECUTABLE 替换为该文件夹中 local-whisper-mcp 的完整路径（Windows 上为 local-whisper-mcp.exe）。

要更改设置，请将其作为环境变量添加到命令中，例如 claude mcp add local-whisper -e LOCAL_WHISPER_LANGUAGE=es -- PATH_TO_EXECUTABLE。

在电脑上使用 claude.ai 聊天

claude.ai 聊天会通过电脑上的 Claude 桌面应用访问服务：

1. 按照 Claude Desktop 中的说明，在 Claude Desktop 中安装扩展。
2. 在 claude.ai 中开始聊天时，点击消息框中的 +，选择 设备，然后在 在以下设备上运行任务 下选择你的电脑。电脑必须处于开机状态，并且 Claude 桌面应用已打开。
3. 附加音频并让 Claude 转录。Claude 会将文件复制到服务的收件箱文件夹中；转录完成后，服务会删除该副本。

技能

技能是可选的，但建议使用。即使没有技能，服务器也能正常工作；不过，技能会告诉 Claude 何时使用服务器、如何向服务器传递聊天附件，以及服务器无法访问时该告诉你什么。没有技能时，在你电脑上运行的 claude.ai 聊天无法访问服务器，可能会尝试在云端转录音频，而不是告诉你如何连接服务器。

要将技能添加到 claude.ai 和 Claude Desktop，请下载 local-whisper-skill.zip，然后在 Settings > Capabilities 下的 Skills 中上传。

要将技能添加到 Claude Code，请从 orihuelaconde marketplace 安装 local-whisper 插件。首先，添加 marketplace：

claude plugin marketplace add OrihuelaConde/claude-plugins

然后安装插件：

claude plugin install local-whisper@orihuelaconde

该插件仅包含技能；请按照 Claude Code 中的说明注册服务器。

使用

用自己的话向 Claude 提问。例如：

• “转录我刚附上的语音备忘录。”
• “转录 C:\Users\me\Recordings\meeting.m4a 并总结其中的决定。”
• “为 ~/Videos/class.mp4 制作西班牙语字幕。”

视频文件比音频文件大得多。如果视频已经在你的电脑上，请将其路径提供给 Claude，而不是将视频附加到聊天中，这样就不必通过聊天来回传输。

该服务器提供三个工具：

工具	功能
transcribe	转录音频文件。参数包括 path（绝对路径）、model、language、format（txt、srt 或 json）和 vad。
status	报告正在使用的设备、已安装模型及其大小、正在进行的下载、收件箱、允许访问的文件夹以及日志文件夹。
delete_models	删除已下载的模型以释放磁盘空间。其说明会告诉 Claude 先征得你的确认。

配置

Claude Desktop 扩展会在其页面上显示这些设置。对于 Claude Code 和其他 MCP 客户端，请将它们设为环境变量：

变量	默认值	说明
LOCAL_WHISPER_MODEL	large-v3-turbo-q8_0	whisper.cpp 的模型列表中的任意模型，可使用名称（base）或文件名（ggml-base.bin）。
LOCAL_WHISPER_LANGUAGE	auto	语言代码，例如 en 或 es；也可以设为 auto 自动检测。
LOCAL_WHISPER_USE_GPU	true	false 表示仅使用 CPU 运行。
LOCAL_WHISPER_RUNTIME	auto	auto、cpu 或 vulkan。如果无法加载某个运行时，则会回退到 CPU。
LOCAL_WHISPER_IDLE_MINUTES	5	模型从内存中卸载前的闲置分钟数。0 表示每次转录后都释放模型。
LOCAL_WHISPER_ALLOWED_ROOTS	你的用户文件夹	服务器可以读取音频的文件夹。在 Windows 上以 ; 分隔，其他系统以 : 分隔。--allowed-roots DIR... 选项会覆盖此设置。
LOCAL_WHISPER_INBOX_DIR	~/.local-whisper-mcp/inbox	客户端复制到电脑上的音频文件夹。服务器会在转录后删除其中的每个文件。
LOCAL_WHISPER_MODELS_DIR	~/.local-whisper-mcp/models	下载模型的文件夹。
LOCAL_WHISPER_AUTO_DOWNLOAD	true	设为 false 可阻止服务器下载缺失的模型。
LOCAL_WHISPER_THREADS	最多 8 个	用于转录的 CPU 线程数。
LOCAL_WHISPER_FFMPEG	自动查找	ffmpeg 可执行文件的完整路径。未设置时，服务器会在 PATH 以及 winget、Scoop、Chocolatey、Homebrew 和 MacPorts 的文件夹中查找。

例如，在首次使用前下载模型（适用于网络连接较慢的情况），请使用 download 命令运行可执行文件：

local-whisper-mcp download large-v3-turbo-q8_0

隐私

• 转录在你的电脑上运行。服务仅在下载模型时联网，模型来自 Hugging Face。你可以通过 LOCAL_WHISPER_AUTO_DOWNLOAD=false 关闭此功能。
• 服务只会读取允许的文件夹和收件箱中的音频，并且只会删除收件箱中的文件：每个文件在转录后删除，任何在收件箱中留存超过一天的文件也会删除。
• ~/.local-whisper-mcp/logs 中的日志记录耗时、设置和错误，不会记录转录文本。 常规日志条目不包含文件名，但错误条目可能包含失败文件的路径，因此分享日志前请先检查。服务会保留一周的日志。

要求

• Windows 10 或更高版本（x64）、macOS（Apple Silicon 或 Intel）或 Linux（x64 或 arm64）。
• x64 系统需要支持 AVX2 的处理器。
• 使用 GPU 时：Windows 和 Linux x64 系统需要 Vulkan 驱动，或使用 Apple Silicon 运行 Metal。若没有 GPU，服务将使用 CPU。
• 可选：对于 WAV、Ogg Opus 和 MP3 以外的格式，需要 ffmpeg。

发布文件未签名。在 macOS 上，如果 Gatekeeper 阻止运行压缩包中的可执行文件，请使用 xattr -dr com.apple.quarantine FOLDER 放行，其中 FOLDER 是解压后的文件夹。

故障排除

• 首次转录需要几分钟。 服务正在下载模型，默认模型大小约为 900 MB。Claude 可以使用 status 工具查看下载进度。
• 搭载 Apple Silicon 的 Mac 首次转录会多花约 15 秒。 macOS 会为每台电脑编译一次 GPU 着色器。
• 录音中有些部分缺失。 请让 Claude 将 vad 设为 false 后重新转录。
• 其他问题。 请查看 ~/.local-whisper-mcp/logs 中今天的日志文件。

从源代码构建

你需要 .NET 10 SDK 和适用于你系统的 Native AOT 先决条件。若要运行测试、发布服务并打包 Claude Desktop 扩展，请在仓库根目录运行以下命令：

dotnet test --project tests/LocalWhisperMcp.Tests

dotnet publish src/LocalWhisperMcp -c Release -r win-x64 -o out

pwsh packaging/mcpb/pack.ps1 -Rid win-x64 -PublishDir out

将 win-x64 替换为你系统的运行时标识符：osx-arm64、osx-x64、linux-x64 或 linux-arm64。Native AOT 只能为运行它的系统构建。

设计说明

仓库中提供了服务设计所依据的测量结果：

• 概念验证结果：说明服务为何采用 C# Native AOT 可执行文件和 Whisper.net，以及默认模型、GPU 后端和音频解码器的选择依据。
• Gemma 4 作为替代引擎：在带有参考转录文本的公开测试集上，将 Gemma 4 E2B、E4B 和 12B 与 Whisper 进行比较。Whisper 仍是唯一的引擎：它的错误更少，而且在没有 GPU 的电脑上，Whisper small 模型的表现与 Gemma 4 相当。

许可证

Local Whisper 基于 MIT License 发布。它包含依据各自许可证授权的组件，详见 THIRD-PARTY-NOTICES.txt。

Local Whisper 是一个独立项目，与 Anthropic 或 OpenAI 没有关联，也未获得其认可。Claude 是 Anthropic, PBC 的商标；本项目仅使用该名称说明它兼容哪些应用。