Whisper MCP

🚀 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）

📚 详细文档

模型信息

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

工作流程示例

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

🔧 技术细节

开发步骤

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

# 构建项目
npm run build

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

📄 许可证

本项目采用 MIT 许可证。