harken

这是什么？适合谁？

harken（montezuma-p/harken，12 Stars，Apache-2.0）是一个 MCP server，解决一个此前被忽视的输入缺口：Agent 不能听音频。你没法把一条 .opus 语音直接递给 Claude。harken 补上这块：给它任意音频（WhatsApp 语音、会议录音、本地文件），它本地转录成文字交回 Agent 读。

它的技术形态很干净：一个 13 MB 的 Rust 单二进制，内嵌 whisper.cpp，完全离线——没有 Python、没有 ffmpeg、没有 API key、任何数据不出机器。同一个二进制身兼三职：MCP server、批量转录 CLI、Claude Code Agent Skill。

接入后暴露两个 MCP 工具：transcribe_file（转录任意音频文件）和 transcribe_whatsapp_export（整包转录 WhatsApp 聊天导出 zip）。任何 MCP 客户端可用：Claude Code、Claude Desktop、Cursor、Windsurf。

README 给出的场景直击痛点：同事用五条 1-2 分钟的语音讲一个任务——你要按顺序听完十分钟，听完还不能搜索、不能引用、没法把关键那句贴进工单。harken 之后：Agent 自己转录、自己读、自己领任务上下文，包括埋在语音中段的那句更正。

适合人群：

• WhatsApp/Telegram 语音消息重度用户（拉美、欧洲、中文语音场景普遍）
• 会议录音自动化处理：整场录音变可搜索文本
• 隐私敏感场景：医疗、法律录音不能上云转录
• 多模态 Agent 开发者：给 Agent 补「听觉」输入通道

不适合：需要说话人分离（diarization）、实时流式转录、多语言同传的场景——当前按 server 实例固定一种模型/语言。

使用前提：Linux/macOS（Windows 未在 README 标注支持）；磁盘放得下模型文件（small 约 466MB）。

准备工作

1. 安装二进制：curl --proto '=https' --tlsv1.2 -LsSf https://github.com/montezuma-p/harken/releases/latest/download/harken-installer.sh | sh
2. MCP 客户端：Claude Code / Claude Desktop / Cursor / Windsurf 任一。
3. 模型：首次调用自动下载（small 约 466MB）；也可预先用 CLI 热身。
4. 成本：Apache-2.0 免费开源；转录全本地零 API 成本。
5. 时间预算：安装 2 分钟；首次模型下载看网速。

快速上手（3 步）

第一步：安装

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/montezuma-p/harken/releases/latest/download/harken-installer.sh | sh

第二步：接入 Claude Code

claude mcp add harken -- harken mcp

或写入 .mcp.json / claude_desktop_config.json：

{
  "mcpServers": {
    "harken": { "command": "harken", "args": ["mcp"] }
  }
}

第三步：让 Agent 听

帮我把这个 WhatsApp 语音导出包整体转录，
按联系人分组，每人挑出有行动项的句子列成清单。

预期结果：Agent 调用 transcribe_whatsapp_export，本地完成转录，返回分组文本并产出行动项清单。

常见踩坑

踩坑 1：首次调用超时

• 现象：客户端因工具调用时间过长而断开。
• 原因：未缓存模型时，首次调用内嵌约 466MB 模型下载。
• 解决：先用 CLI 预热：harken --model small some.opus，跑完模型即入缓存。

踩坑 2：语言/模型想换

• 现象：默认 small 模型 + pt（葡萄牙语）语言。
• 原因：模型、语言、设备按 server 实例固定：harken mcp --model medium --lang auto。
• 解决：中文用户显式启动带 --lang zh（或 auto）的实例；两种语言就跑两个 server 条目。

踩坑 3：WhatsApp 导出格式

• 现象：直接丢了个文件夹。
• 原因：transcribe_whatsapp_export 吃的是聊天导出 zip。
• 解决：在 WhatsApp 里「导出聊天」生成 zip 再交给 Agent。

踩坑 4：中文识别质量

• 现象：small 模型对中文专有名词错字多。
• 原因：small 模型体积小、精度有限。
• 解决：换 --model medium（更大更准更慢），或对关键段落人工复核。

踩坑 5：CPU 推理慢

• 现象：长录音转录耗时长。
• 原因：默认 cpu 设备。
• 解决：如机器有加速器，用 --device 相应参数；或接受批量后台跑。

踩坑 6：22 个 open issues 的早期状态

• 现象：可能遇到边界 bug。
• 原因：项目早期（2026-08-18 创建），issue 数（22）多于 star 数（12），说明有真实用户在踩坑报障。
• 解决：报障前先搜 issue 区；生产关键路径做好降级（本地 CLI 直跑）。

初级用法

1. 单条语音→工单：收到语音丢给 Agent：「转录这条，提取待办」。
2. 会议纪要：整场录音 → transcribe_file → Agent 按模板出纪要。
3. 批量归档：一个目录的 mp3 全部转录成 txt 入库，用 CLI 一次跑完。
4. 面试/播客整理：转成带时间戳的文本再让 Agent 摘要点。

高级玩法

1. 双语言双实例：一个 --lang pt 一个 --lang zh 同时挂进客户端，按消息来源路由。
2. 语音驱动的任务系统：把「语音→转录→行动项→工单」串成自动化，语音即任务入口。
3. 隐私合规转录管线：医疗/法律录音全程不出内网，harken 本地转录 + 本地 LLM 总结。
4. 与字幕工具链组合：转录文本 + ffmpeg 生成 SRT 字幕草稿，再人工校对。

小技巧

1. 先 CLI 热身再接 MCP：避免首次调用的模型下载超时。
2. 模型按需选：日常 small 够用，关键内容上 medium。
3. 配合 Agent 的「读后动作」：转录只是手段，让 Agent 直接接「提取行动项/回复消息」。
4. issue 区当 changelog 看：项目活跃迭代中，star 少 issue 多恰说明真实使用密度高。
5. 中文场景显式指定 --lang：别依赖默认值。

常见问题 FAQ

Q1：支持说话人分离吗？

A：当前两个工具都不做 diarization；需要区分说话人的场景要后处理或等上游更新。来源：README

Q2：完全离线吗？

A：是——除首次模型下载外全程本地，无 API key、无云端调用。来源：README

Q3：Windows 能用吗？

A：README 安装路径面向 Linux/macOS；Windows 未标注支持，可关注 WSL 路径与后续 release。

Q4：转录质量如何？

A：取决于所选 whisper.cpp 模型档位；README 官方示例为葡萄牙语语音，中文表现未实测，建议 medium 档起步。

Q5：和云端转录 API 比呢？

A：隐私与成本占优（零 API 费、数据不出机）；准确率与流式能力弱于顶级云服务，按场景取舍。

进阶学习建议

• 吃透「三合一形态」：同一个二进制是 MCP server / 批量 CLI / Agent Skill 三种入口，读 README 的三段用法，理解何时走 MCP（Agent 交互）、何时走 CLI（批量离线）——这个设计模式值得借鉴到自己的工具开发。
• 模型/语言/设备的实例化设计：harken 把配置固化在 server 启动参数而非每次请求，读它的参数文档，思考这种取舍（简单 vs 灵活）对多语言场景的影响。
• 补齐多模态输入面：把 harken（听觉）与图像理解、PDF 解析类 MCP 组合，拼出「什么都能喂」的 Agent 输入层。

参考链接

• harken GitHub 仓库
• whisper.cpp 项目
• MCP 协议官网

免责声明：本文基于官方仓库 README 与 GitHub 公开数据整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。中文转录质量、Windows 支持等未实测项已在文中标注。