whispernotes

Whisper Notes MCP 服务和 CLI

通过 MCP 服务和命令行访问 Whisper Notes——适用于 Mac 和 iPhone 的设备端语音转文字工具。Claude 和任何 MCP 客户端都可以搜索你的转录记录、读取转录文本（纯文本、带时间戳或带说话人标签），还可以转录音频或视频文件。

100% 在设备端运行。 服务通过本地 Unix 套接字（权限为 0600）通信——没有开放端口、没有网络接口，也不使用云服务。你的音频和转录文本绝不会离开你的 Mac。

MCP 服务内置于 Whisper Notes Mac 应用中——无需运行 npx 或 pip install。本仓库是其文档和注册目录所在之处。权威文档位于 whispernotes.app/cli-mcp（Agent 可读的 Markdown：whispernotes.app/cli-mcp.md）。

设置

1. 下载 Whisper Notes for Mac，版本为 1.5.5 或更高版本——Direct Download（DMG）版本（Mac App Store 版本不包含 Local API）。需要 macOS 14+ 和 Apple Silicon。
2. 打开应用 → Settings → Integrations → 开启 Local CLI & MCP。
3. 点击同一部分中的 Install CLI——这会将 whispernotes（以及名称可用时的简写 wn）安装到你的终端中。

连接 Claude 或任何 MCP 客户端

Claude Code——一行命令：

claude mcp add whispernotes -- whispernotes mcp

Claude Desktop——将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "whispernotes": {
      "command": "/usr/local/bin/whispernotes",
      "args": ["mcp"]
    }
  }
}

使用 which whispernotes 输出的完整路径——图形界面应用不会读取你的 shell PATH。其他任何本地 MCP 客户端（Cursor 等）也采用相同方式：命令为 whispernotes，参数为 ["mcp"]。传输方式为 stdio；没有 HTTP 端点。

然后只需提出请求：

• “读取我最近五份转录记录，并告诉我有哪些事项需要跟进。”
• “找到我们讨论发票的那场会议，并起草一封回复邮件。”
• “转录 ~/Desktop/podcast.mp3，并提取所有待办事项。”

MCP 工具

工具	参数	返回内容
list_transcripts	limit（默认 20） · source	最近的转录记录，包含 ID、日期和标题
search_transcripts	query（必填） · limit	包含片段的全文搜索匹配结果
get_transcript	id（必填） · timestamps · speakers · max_chars · offset	一份转录记录的文本
get_latest_transcript	timestamps · speakers	最近的一份转录记录
transcribe_file	path（必填）	转录音频或视频文件，并将其保存到记录中
list_models	—	已安装的模型以及当前启用的模型

长录音会分段读取：当转录文本超过 max_chars 时，响应末尾会显示明确的截断标记，告知 Agent 后续应从哪个 offset 继续——时长一小时的会议也不会超出上下文窗口。

CLI

同一个二进制文件也是一个功能完整的命令行工具：

$ whispernotes status
WhisperNotes 1.5.5 (340) · SenseVoice Small · ready · 3081 notes

$ whispernotes list --limit 3
9f3c21a8  2026-08-01 09:14  0:42   meeting   Weekly sync — pricing review
b2d84e07  2026-07-31 18:03  12:26  recorded  Idea dump on the walk home
5a1f9c33  2026-07-30 10:52  47:10  imported  interview-with-anna.m4a

$ whispernotes show latest | ollama run llama3 "Summarize the key points:"

$ whispernotes export --format md --audio --output-dir ~/Transcripts
✓ exported 312/312 transcript(s), 312 audio file(s) → /Users/you/Transcripts

命令	选项	功能
status	—	应用版本、当前模型、就绪状态、笔记数量
list	--limit N · --source T · --json	按时间倒序列出最近的转录文本
search <query>	--limit N · --json	在所有历史记录中进行全文搜索，并提供摘要片段
show [id or latest]	--timestamps · --speakers · --max-chars N · --offset N · --json	打印一条转录文本（默认使用 latest）
transcribe <file>	--json	转录音频或视频文件，并保存到历史记录
export	--format txt or md · --output-dir DIR · --source T · --limit N · --audio · --speakers	批量导出转录文本，也可同时复制音频文件
models	list · select <id>	列出或切换模型：parakeet、sensevoice、whisper-small、whisper-large-v3-turbo
language	list · select <code>	列出或切换转录语言——可选项取决于当前模型
mcp	—	通过标准输入/输出运行 MCP 服务
version · help	—	CLI 版本 · 用法

结果输出到标准输出，进度信息和错误输出到标准错误——可安全地通过管道传输或重定向。--json 始终输出单个 JSON 对象或数组。whispernotes help 会打印完整用法；命令使用有误时，会显示对应的精确用法行。wn 是一个便捷别名——脚本和 Agent 应调用始终可用的 whispernotes。

隐私与安全

• 使用位于 ~/Library/Application Support/WhisperNotes/api.sock 的 Unix 域套接字进行通信，权限为 0600——只有你的 macOS 用户账户可以连接。没有 TCP 端口，也没有网络接口，其他任何机器都无法访问。
• 默认关闭：除非你在“设置”中启用开关，否则不会提供任何服务。
• Claude 等 MCP 客户端会在每次调用工具前征求你的批准。
• 转录在设备本地运行（通过神经网络引擎 / MLX 运行 Parakeet V3、Whisper、SenseVoice）；结果仅保存在本地历史记录中。

链接

• 文档：whispernotes.app/cli-mcp · 提供给 Agent 的原始 Markdown：/cli-mcp.md
• 下载：Mac 版 Whisper Notes（DMG）
• iPhone 和 Mac App Store：App Store
• 网站：whispernotes.app · 更新日志 · 隐私政策
• 支持：[email protected]

许可证

本仓库的内容（文档和元数据）采用 MIT 许可证。Whisper Notes 本身——包括应用程序、内置 MCP 服务和 CLI——是商业软件；条款请参阅 whispernotes.app。