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 許可證。