使用说明

项目简介

MCP Server Whisper 是一个实现了 Model Context Protocol (MCP) 的服务器，专注于音频处理功能。它利用 OpenAI 的 Whisper 和 GPT-4o 模型，为支持 MCP 协议的客户端（如 Claude）提供强大的音频转录、基于音频内容的对话以及文本转语音能力。通过标准化的 MCP 接口，AI 助手可以轻松调用这些音频处理工具，实现更智能的交互。

主要功能点

高级音频文件管理：支持通过正则表达式、文件元数据（大小、时长、修改时间、格式）进行音频文件搜索、过滤和排序。
多格式音频处理：支持多种音频格式（flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm）的转录和处理，以及 mp3 和 wav 格式的音频聊天。
智能音频转录：
- 支持 OpenAI Whisper 模型 ('whisper-1') 以及更先进的 'gpt-4o-transcribe' 和 'gpt-4o-mini-transcribe' 模型。
- 提供自定义 Prompt 功能，可以引导转录结果，例如修正特定词汇、保持上下文或规范标点。
- 支持多种时间戳粒度（词级别、段落级别），方便精细化分析。
- 提供增强型转录模板（详细、叙事、专业、分析型），满足不同场景需求。
交互式音频聊天：
- 使用 GPT-4o 音频模型 ('gpt-4o-audio-preview-', 'gpt-4o-mini-audio-preview-')，实现基于音频内容的对话。
- 支持自定义系统和用户 Prompt，控制对话风格和内容。
高质量文本转语音：
- 使用 OpenAI TTS API，支持 'gpt-4o-mini-tts' 等模型。
- 提供多种音色选择 (alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer) 和语速调节。
- 支持长文本处理，自动分割并合并音频片段。
高性能和高效率：
- 并行批量处理多个音频文件，提高处理速度。
- 高性能缓存机制，加速重复操作。
- 自动音频文件压缩，处理超过 API 大小限制的文件。

安装步骤

克隆仓库:

git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

安装依赖 (推荐使用 uv):
```
uv sync
```

设置 pre-commit hooks (可选，但推荐):

uv run pre-commit install

配置环境变量: 创建 '.env' 文件，并填入 OpenAI API 密钥和音频文件路径：

OPENAI_API_KEY=YOUR_OPENAI_API_KEY
AUDIO_FILES_PATH=/path/to/your/audio/files

请将 'YOUR_OPENAI_API_KEY' 替换为你的 OpenAI API 密钥，'/path/to/your/audio/files' 替换为你存放音频文件的目录。

服务器配置

以下是配置 MCP Server Whisper 服务器连接 Claude Desktop 或其他 MCP 客户端的 'claude_desktop_config.json' 示例。你需要将这段 JSON 配置添加到你的客户端配置文件中。

{
  "mcpServers": {
    "whisper": {  // 服务器名称，可以自定义，例如 "audio-server"
      "command": "uvx", // 启动命令，uvx 是 uv 提供的运行 Python 程序的命令
      "args": [ // 启动参数
        "--with", // uvx 的参数，用于指定需要包含的 Python 包
        "aiofiles", // 异步文件操作库
        "--with",
        "mcp[cli]", // MCP 协议库及其命令行工具
        "--with",
        "openai", // OpenAI Python 库
        "--with",
        "pydub", // 音频处理库
        "mcp-server-whisper" // 指定运行 mcp-server-whisper 项目
      ],
      "env": { // 环境变量
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY", // 你的 OpenAI API 密钥，请替换为实际密钥
        "AUDIO_FILES_PATH": "/path/to/your/audio/files" // 音频文件存放路径，请替换为实际路径
      }
    }
  }
}

注意: 请将 'YOUR_OPENAI_API_KEY' 和 '/path/to/your/audio/files' 替换为你在 '.env' 文件中设置的实际值。

基本使用方法

配置完成后，在支持 MCP 协议的客户端（例如 Claude Desktop）中，你可以通过自然语言指令调用 MCP Server Whisper 提供的音频处理功能。

示例指令:

音频转录:
- 'Claude, please transcribe my latest audio file.' (转录最新音频文件)
- 'Claude, transcribe the audio file named "meeting.mp3" with detailed insights.' (转录指定文件并进行详细分析)
- 'Claude, create a professional transcript for all MP3 files containing "interview" in the filename.' (批量转录文件名包含 "interview" 的 MP3 文件，生成专业转录)
音频聊天:
- 'Claude, analyze this audio file and summarize the main points.' (分析音频文件并总结要点)
- 'Claude, listen to this audio and tell me the speaker's sentiment.' (分析音频情感)
文本转语音:
- 'Claude, create a claudecast with the script: "Hello, world! This is a test." using the shimmer voice.' (使用 shimmer 音色将指定文本转换为语音)
- 'Claude, generate an audio version of "The quick brown fox jumps over the lazy dog." with a fast speed.' (快速语速将指定文本转换为语音)

更多使用示例和高级用法请参考仓库 README 文档。

关键词