JinDaGe - whisper-mcp MCP Details

article

README

🚀 Whisper MCP 服务器

这是一个轻量级的 MCP（模型上下文协议）服务器，可使用 whisper.cpp 进行本地音频转录。目前存在多个 Whisper MCP 实现，本项目是其中最精简的一个，并且可与 apple-voice-memo-mcp 配合使用，以实现完整的语音备忘录工作流程。

✨ 主要特性

本地转录：所有处理均在本地机器上完成。
多模型支持：可从 tiny、base、small、medium 或 large 模型中进行选择。
多种格式支持：支持 wav、mp3、m4a 等多种音频格式。
时间戳功能：可选择输出带或不带时间戳的转录结果。

📦 安装指南

环境要求

macOS（在 Apple Silicon 上测试过）
Node.js 18+
安装 whisper-cpp：brew install whisper-cpp
安装 ffmpeg：brew install ffmpeg

安装命令

npm install -g whisper-mcp

或者直接运行：

npx whisper-mcp

💻 使用示例

配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

编辑完成后，重启 Claude Desktop。

配置 Claude Code (CLI)

对于 Claude Code，将以下内容添加到项目的 .mcp.json 文件中：

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

或者，如果要进行全局用户配置，将其添加到 ~/.claude/settings.json 中：

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

提示：在 Claude Code 中使用 /mcp 命令来验证服务器是否已连接。

本地开发设置

如果从源代码运行而不是通过 npm 安装：

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "node",
      "args": ["/path/to/whisper-mcp/dist/index.js"]
    }
  }
}

与 Apple Voice Memos MCP 配合使用

为实现完整的语音备忘录工作流程，可与 apple-voice-memo-mcp 一起使用：

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "npx",
      "args": ["-y", "apple-voice-memo-mcp"]
    },
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

MCP 工具使用示例

`transcribe_audio`

使用 Whisper 转录音频文件。参数：

file_path（必填）：音频文件的绝对路径
model（可选）：要使用的模型（tiny.en、base.en、small.en、medium.en、large）。默认值：base.en
language（可选）：语言代码。默认值：en
output_format（可选）：text、timestamps 或 json。默认值：text

示例：

{
  "file_path": "/path/to/audio.m4a",
  "model": "medium.en",
  "output_format": "timestamps"
}

`list_whisper_models`

列出可用的 Whisper 模型及其下载状态。 返回结果：

{
  "models": [
    {
      "name": "base.en",
      "size": "142 MB",
      "downloaded": true,
      "path": "/Users/you/.whisper/ggml-base.en.bin"
    }
  ]
}

`download_whisper_model`

下载 Whisper 模型以供本地使用。参数：

model（必填）：要下载的模型（tiny.en、base.en、small.en、medium.en、large）

📚 详细文档

模型信息

| 模型 | 大小 | 速度 | 质量 | |------|------|------|------| | tiny.en | 75 MB | 最快 | 基础 | | base.en | 142 MB | 快 | 良好 | | small.en | 466 MB | 中等 | 较好 | | medium.en | 1.5 GB | 慢 | 优秀 | | large | 2.9 GB | 最慢 | 最佳 |

模型存储在 ~/.whisper/ 目录下。

工作流程示例

列出语音备忘录：list_voice_memos
获取音频路径：使用备忘录 ID 调用 get_audio
转录音频：使用文件路径调用 transcribe_audio
保存到存储库

🔧 技术细节

开发步骤

# 克隆并安装依赖
git clone https://github.com/jwulff/whisper-mcp.git
cd whisper-mcp
npm install

# 构建项目
npm run build

# 使用 MCP 检查器进行测试
npm run inspector

📄 许可证

本项目采用 MIT 许可证。

whisper-mcp