macwhisper-mcp-server

macwhisper-mcp-server

连接 MacWhisper 与 Claude Desktop 的本地 MCP 服务。

功能： 将音频文件放到桌面上，然后让 Claude 一步完成转录、总结或提取待办事项。MacWhisper 在你的 Mac 上转录，Claude 负责思考。所有数据都不会离开你的设备。无需云端 API。数据绝不会离开你的 Mac。

Audio file  →  MacWhisper CLI  →  MCP server  →  Claude Desktop

---

---

要求

• macOS（MacWhisper 仅支持 macOS）
• MacWhisper — 已安装并获得许可
• 启用 MacWhisper CLI：打开 MacWhisper → Settings → Advanced → Command-Line Tool → Install。这会将 mw 放到 /usr/local/bin/mw。
• 通过 pyenv 安装 Python 3.13.x
• Claude Desktop

通过 Homebrew 安装 MacWhisper：

brew install --cask macwhisper

安装后，按上述步骤在 MacWhisper Settings 中启用 CLI。之后运行 brew upgrade --cask macwhisper 时，CLI 符号链接会自动更新，无需重新安装。

---

安装

选项 A — Homebrew（推荐）

brew tap docdyhr/tap
brew install docdyhr/tap/macwhisper-mcp-server

这会将 macwhisper-mcp 二进制文件安装到 Homebrew 前缀目录。之后可通过 brew upgrade docdyhr/tap/macwhisper-mcp-server 升级。

选项 B — pip / 源码

pip install macwhisper-mcp-server

或者从源码安装：

git clone https://github.com/docdyhr/macwhisper-mcp-server.git
cd macwhisper-mcp-server

pyenv install 3.13.13   # skip if already installed
pyenv local 3.13.13
python -m venv .venv
source .venv/bin/activate
pip install -e .

验证 MacWhisper CLI 是否可用：

mw version

---

配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "macwhisper": {
      "command": "macwhisper-mcp",
      "args": [],
      "env": {
        "MACWHISPER_ALLOWED_PATHS": "~/Desktop:~/Downloads",
        "FASTMCP_CHECK_FOR_UPDATES": "off"
      }
    }
  }
}

重启 Claude Desktop。

注意： 在让 Claude 转录音频文件之前，必须先将文件保存到 Mac 的文件系统中（桌面、下载文件夹或其他已允许的文件夹）。直接上传到 Claude 聊天窗口的文件位于 Claude 的容器中，本地 MacWhisper CLI 无法访问。

验证是否正常运行

在 Claude Desktop 中提问：

转录 ~/Desktop/memo.m4a

你应该会看到调用 transcribe_audio 工具，随后显示转录文本。

---

可用工具

工具	描述
transcribe_audio(path, model?, language?, persist?, engine?)	转录音频文件，并以纯文本形式返回转录内容。language 是 ISO 639-1 代码（例如 da）或 auto；会覆盖任何按目录设置的默认值。persist=true 会将转录内容保存到 MacWhisper 历史记录中（仅适用于 MacWhisper 引擎）。engine 为 "macwhisper"（默认）或 "whisper-cpp"——见下文的替代引擎。
list_models()	列出 MacWhisper 中已安装的转录模型；如果配置了 MACWHISPER_WHISPERCPP_MODEL_DIR，也会列出 whisper-cpp 模型；当前启用的 MacWhisper 模型会标记出来
cancel_transcription()	取消当前正在运行的转录
list_allowed_paths()	返回服务获准读取的目录
start_watch(folder)	监视文件夹，并将新音频文件自动转录到 ../done/
stop_watch()	停止当前活动的文件夹监视器
get_watch_results()	返回已完成的监视文件夹转录结果，并清空队列

支持的音频格式：.m4a .mp3 .mp4 .mov .wav .aiff .flac

---

配置

所有配置均通过环境变量完成。对于 Claude Desktop，将环境变量通过 env 字典传入 claude_desktop_config.json；本地开发时则在 .env 中设置。

环境变量	默认值	描述
MACWHISPER_ALLOWED_PATHS	~/Desktop	服务可读取的目录列表，以冒号分隔
MACWHISPER_CLI	自动检测	mw 二进制文件的路径。如果该文件存在，默认为 /Applications/MacWhisper.app/Contents/MacOS/mw；否则默认为 PATH 中的 mw
MACWHISPER_LOG_PATH	~/Library/Logs/macwhisper-mcp.log	日志文件路径（绝不输出到 stdout——该输出专供 MCP 使用）
MACWHISPER_LANGUAGE_DEFAULTS	无	以冒号分隔的 dir=lang 对（ISO 639-1，或 auto）——匹配目录中的文件会自动设置 --language。优先使用最具体的目录；显式指定的 language 参数始终具有更高优先级。
MACWHISPER_WHISPERCPP_BINARY	PATH 中的 whisper-cli	whisper-cli 二进制文件的路径（如果它不在 PATH 中）。仅在 engine="whisper-cpp" 时使用。
MACWHISPER_WHISPERCPP_MODEL_DIR	无	包含 GGML .bin 模型文件的目录。必须设置此项才能使用 engine="whisper-cpp"——见下文。

**本地开发：**将 .env.example 复制为 .env 并进行调整。使用 direnv 时，.envrc 会自动导出 .env 中的变量。不使用 direnv 时：source .env。

按目录设置语言默认值

如果你经常转录特定语言的录音，可以将某个子文件夹映射到该语言， 这样就不必每次调用都传入 language：

"MACWHISPER_LANGUAGE_DEFAULTS": "~/Desktop/DK=da:~/Desktop/DE=de"

将文件放入 ~/Desktop/DK/ 后，transcribe_audio 会自动传入 --language da。 在工具调用中显式指定的 language 参数始终优先于目录默认值。

替代引擎：whisper.cpp

transcribe_audio(..., engine="whisper-cpp") 使用独立的 whisper.cpp 二进制文件进行转录，而不是使用 MacWhisper——适合没有 MacWhisper 许可证，或希望使用完全开源的本地方案的情况。它不会以任何方式影响 MacWhisper。

设置：

brew install whisper-cpp

Homebrew 只会安装 whisper-cli 二进制文件，不包含模型。请自行下载 GGML 模型（此服务绝不会从网络下载任何内容），下载地址为 huggingface.co/ggerganov/whisper.cpp， 例如 ggml-base.en.bin，并将其放入你选择的目录，然后将服务指向该文件：

"MACWHISPER_WHISPERCPP_MODEL_DIR": "~/whisper-models"

然后使用模型文件名调用工具（不要使用 MacWhisper 的 engine:model-id 字符串）：

使用 whisper-cpp 引擎和模型 ggml-base.en.bin 转录 ~/Desktop/memo.wav

限制（v1）：

• 输入格式仅支持 .wav、.mp3、.flac，不支持 .m4a/.mp4/.mov/.aiff。这是 whisper.cpp 自身原生格式支持的限制；请先转换其他格式（例如使用 ffmpeg），或使用默认的 MacWhisper 引擎，该引擎支持所有受支持的格式。
• 不支持 persist=true——whisper.cpp 没有历史记录机制。
• 如果未设置 language 或目录默认值，则默认语言为英语（en）；MacWhisper 则使用应用自身选择的语言。

---

开发

source .venv/bin/activate
pip install -e ".[dev]"

# Tests
pytest -q

# Lint + format
ruff check .
ruff format .

# Pre-commit hooks (one-time setup)
pip install pre-commit
pre-commit install

# Smoke-test against a real audio file (server must not be running in Claude Desktop)
python scripts/smoke_test.py ~/Downloads/Test.m4a

日志

tail -f ~/Library/Logs/macwhisper-mcp.log

---

安全

• 所有文件路径都会经过解析（跟随符号链接），并在传递给 CLI 前与 MACWHISPER_ALLOWED_PATHS 允许列表进行核对。
• 始终使用 argv 列表调用 subprocess.run，绝不使用 shell=True。
• 绝不进行网络调用。

完整的威胁模型请参阅 PRD §7。

---

已知限制

• 上传的文件： 拖入 Claude 聊天窗口的文件位于 Claude 的容器中，本地 MacWhisper CLI 无法访问。请将文件保存到桌面或下载文件夹（或其他允许列表中的目录），然后让 Claude 从那里转录。
• 丹麦语字母名称： 单独念出字母名称时，Whisper 可能会按发音近似转写（例如，“Æ, Ø, Å” → “E, Y, U”）。字母位于单词内部时则能正确转写。这是 Whisper 引擎的限制，并非此封装程序的错误。请参阅 PRD §12。
• 冷启动延迟： MacWhisper 启动后的首次转录需要约 13 秒（加载模型）。后续调用约需 2 秒。

---

许可证

MIT——请参阅 LICENSE。