MCP Server Whisper

<div align="center">

一个使用 OpenAI 的 Whisper 和 GPT-4o 模型进行高级音频转录和处理的模型上下文协议 (MCP) 服务器。

</div>

概述

MCP Server Whisper 提供了一种标准化的方式，通过 OpenAI 最新的转录和语音服务处理音频文件。通过实现 模型上下文协议，它使像 Claude 这样的 AI 助手能够无缝地与音频处理功能交互。

主要特性：

• 🔍 高级文件搜索，具有正则表达式模式、文件元数据过滤和排序功能
• 🔄 并行批量处理，用于多个音频文件
• 🔄 格式转换，在支持的音频类型之间进行转换
• 📦 自动压缩，用于超大文件
• 🎯 多模型转录，支持所有 OpenAI 音频模型
• 🗣️ 交互式音频聊天，使用 GPT-4o 音频模型
• ✏️ 增强转录，具有专门的提示和时间戳支持
• 🎙️ 文本转语音生成，具有可定制的声音、指令和速度
• 📊 全面的元数据，包括持续时间、文件大小和格式支持
• 🚀 高性能缓存，用于重复操作

安装

# 克隆仓库
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_KEY=your_openai_api_key
AUDIO_FILES_PATH=/path/to/your/audio/files

用法

启动服务器

要在开发模式下运行 MCP 服务器：

mcp dev src/mcp_server_whisper/server.py

要安装服务器以与 Claude Desktop 或其他 MCP 客户端一起使用：

mcp install src/mcp_server_whisper/server.py [--env-file .env]

暴露的 MCP 工具

音频文件管理

• list_audio_files - 列出具有全面过滤和排序选项的音频文件：
  • 按文件名上的正则表达式模式进行过滤
  • 按文件大小、持续时间、修改时间或格式进行过滤
  • 按名称、大小、持续时间、修改时间或格式进行排序
  • 所有操作都支持并行批量处理
• get_latest_audio - 获取最近修改的音频文件，并包含模型支持信息

音频处理

• convert_audio - 将音频文件转换为支持的格式（mp3 或 wav）
• compress_audio - 压缩超过大小限制的音频文件

转录

• transcribe_audio - 使用 OpenAI 模型进行高级转录：

  • 支持 whisper-1、gpt-4o-transcribe 和 gpt-4o-mini-transcribe
  • 用于引导转录的自定义提示
  • 用于单词和段级别定时的可选时间戳粒度
  • JSON 响应格式选项

• chat_with_audio - 使用 GPT-4o 音频模型进行交互式音频分析：

  • 支持 gpt-4o-audio-preview-2024-10-01、gpt-4o-audio-preview-2024-12-17 和 gpt-4o-mini-audio-preview-2024-12-17
  • 自定义系统和用户提示
  • 提供对音频内容的对话式响应

• transcribe_with_enhancement - 使用专门的模板进行增强转录：

  • detailed - 包括语气、情感和背景细节
  • storytelling - 将转录转换为叙述形式
  • professional - 创建正式的、适合商务的转录
  • analytical - 添加对语音模式和关键点的分析

文本转语音

• create_claudecast - 使用 OpenAI 的 TTS API 生成文本转语音音频：
  • 支持 gpt-4o-mini-tts (首选) 和其他语音模型
  • 多种声音选项（alloy、ash、coral、echo、fable、onyx、nova、sage、shimmer）
  • 速度调整和自定义指令
  • 可自定义的输出文件路径
  • 通过自动分割和连接音频片段来处理任意长度的文本

支持的音频格式

模型	支持的格式
转录	flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
聊天	mp3, wav

注意： 大于 25MB 的文件会自动压缩以满足 API 限制。

与 Claude 的示例用法

<details> <summary>基本音频转录</summary>

Claude, 请转录我最新的音频文件，并提供详细的见解。

Claude 将自动：

1. 使用 get_latest_audio 查找最新的音频文件
2. 确定适当的转录方法
3. 使用 "detailed" 模板通过 transcribe_with_enhancement 处理文件
4. 返回增强的转录 </details>

<details> <summary>高级音频文件搜索和过滤</summary>

Claude, 列出我所有时长超过 5 分钟且在 2024 年 1 月 1 日之后创建的音频文件，并按大小排序。

Claude 将：

1. 将日期转换为时间戳
2. 使用 list_audio_files 和适当的过滤器：
   • min_duration_seconds: 300 (5 分钟)
   • min_modified_time: <2024 年 1 月 1 日的时间戳>
   • sort_by: "size"
3. 返回匹配音频文件的排序列表，并包含全面的元数据 </details>

<details> <summary>批量处理多个文件</summary>

Claude, 查找文件名中包含 "interview" 的所有 MP3 文件，并为每个文件创建专业的转录。

Claude 将：

1. 使用 list_audio_files 搜索文件，并使用：
   • pattern: ".*interview.*\\.mp3"
   • format: "mp3"
2. 使用 transcribe_with_enhancement 并行处理所有匹配的文件
   • enhancement_type: "professional"
   • model: "gpt-4o-mini-transcribe" (为了效率)
3. 在格式良好的输出中返回所有转录 </details>

<details> <summary>使用 Claudecast 生成文本转语音</summary>

Claude, 使用以下脚本创建一个 claudecast："欢迎收听我们的播客！今天我们将讨论 2025 年的人工智能趋势。" 使用 shimmer 声音。

Claude 将：

1. 使用 create_claudecast 工具，并使用：
   • 包含脚本的 text_prompt
   • voice: "shimmer"
   • model: "gpt-4o-mini-tts" (默认高质量模型)
   • instructions: "以热情、播客主持人的风格说话" (可选)
   • speed: 1.0 (默认，可以调整)
2. 生成音频文件并将其保存到配置的音频目录
3. 提供生成的音频文件的路径 </details>

使用 Claude Desktop 进行配置

将此添加到您的 claude_desktop_config.json：

UVX

{
  "mcpServers": {
    "whisper": {
      "command": "uvx",
      "args": [
        "--with",
        "aiofiles",
        "--with",
        "mcp[cli]",
        "--with",
        "openai",
        "--with",
        "pydub",
        "mcp-server-whisper"
      ],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "AUDIO_FILES_PATH": "/path/to/your/audio/files"
      }
    }
  }
}

推荐 (仅限 Mac OS)

• 安装 Screen Recorder By Omi (免费)
• 将 AUDIO_FILES_PATH 设置为 /Users/<user>/Movies/Omi Screen Recorder 并将 <user> 替换为您的用户名
• 当您使用该应用程序录制音频时，您可以直接使用 Claude 转录大批量音频

开发

本项目使用现代 Python 开发工具，包括 uv、pytest、ruff 和 mypy。

# 运行测试
uv run pytest

# 运行覆盖率测试
uv run pytest --cov=src

# 格式化代码
uv run ruff format src

# 检查代码风格
uv run ruff check src

# 运行类型检查 (严格模式)
uv run mypy --strict src

# 运行 pre-commit hooks
pre-commit run --all-files

CI/CD 工作流程

该项目使用 GitHub Actions 进行 CI/CD：

1. 代码风格检查和类型检查: 使用 ruff 和严格的 mypy 类型检查确保代码质量
2. 测试: 在多个 Python 版本 (3.10, 3.11) 上运行测试
3. 构建: 创建分发包
4. 发布: 当推送新的版本标签时，自动发布到 PyPI

要创建新的发布版本：

git checkout main
# 确保一切都是最新的
git pull
# 创建新的版本标签
git tag v0.1.1
# 推送标签
git push origin v0.1.1

工作原理

有关详细的架构信息，请参阅 架构文档。

MCP Server Whisper 构建在模型上下文协议之上，该协议标准化了 AI 模型与外部工具和数据源交互的方式。服务器：

1. 暴露音频处理能力: 通过标准化的 MCP 工具接口
2. 实现并行处理: 使用 asyncio 和批量操作来提高性能
3. 管理文件操作: 处理检测、验证、转换和压缩
4. 提供丰富的转录: 通过不同的 OpenAI 模型和增强模板
5. 优化性能: 使用缓存机制进行重复操作

底层使用：

• pydub 用于音频文件操作
• asyncio 用于并发处理
• OpenAI 最新的转录模型（包括 gpt-4o-transcribe）
• OpenAI 的 GPT-4o 音频模型，用于增强理解
• OpenAI 的 gpt-4o-mini-tts，用于高质量的语音合成
• FastMCP 用于简化 MCP 服务器实现
• 整个代码库中使用类型提示和严格的 mypy 验证

贡献

欢迎贡献！请按照以下步骤操作：

1. Fork 仓库
2. 为您的功能创建一个新分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试和代码风格检查 (uv run pytest && uv run ruff check src && uv run mypy --strict src)
5. 提交您的更改 (git commit -m 'Add some amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开一个 Pull Request

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 模型上下文协议 (MCP) - 用于协议规范
• pydub - 用于音频处理
• OpenAI Whisper - 用于音频转录
• FastMCP - 用于 MCP 服务器实现
• Anthropic Claude - 用于自然语言交互

---

<div align="center"> 用 ❤️ 由 <a href="https://github.com/arcaputo3">Richie Caputo</a> 制作 </div>