MCP Server Whisper

MCP Server Whisper

警告

此项目已迁移。 活跃开发已转移至 TJC-LP/sanzaru。此仓库不再维护，并将归档。请将依赖项和问题更新至新仓库。

概述

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

主要功能：

• 🔍 高级文件搜索，支持正则表达式模式、文件元数据筛选和排序
• ⚡ 原生 MCP 并行处理——可同时调用多个工具
• 🔄 在支持的音频类型之间进行格式转换
• 📦 自动压缩超大文件
• 🎯 多模型转录，支持所有 OpenAI 音频模型
• 🗣️ 使用 GPT-4o 音频模型进行交互式音频聊天
• ✏️ 增强型转录，支持专用提示词和时间戳
• 🎙️ 文本转语音生成，可自定义语音、指令和语速
• 📊 全面的元数据，包括时长、文件大小和格式支持情况
• 🚀 针对重复操作的高性能缓存
• 🔒 使用 Pydantic 模型为所有工具输出提供类型安全的响应

注意： 此项目为非官方项目，与 OpenAI 无关联，也未获得 OpenAI 的认可或赞助。它为 OpenAI 公开提供的 API 提供模型上下文协议接口。

安装

# Clone the repository
git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

# Using uv 
uv sync

# Set up pre-commit hooks
uv run pre-commit install

环境设置

根据提供的 .env.example 创建 .env 文件：

cp .env.example .env

使用实际值编辑 .env：

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

注意： 环境变量必须在运行时可用。使用 Claude 进行本地开发时，请使用 dotenv-cli 等工具加载环境变量（见下文“用法”部分）。

用法

使用 Claude 进行本地开发

项目包含一个 .mcp.json 配置文件，用于使用 Claude 进行本地开发。使用方法如下：

1. 确保已在 .env 文件中配置所需的环境变量
2. 加载环境变量后启动 Claude：

bunx dotenv-cli -- claude

这将：

• 从 .env 文件加载环境变量
• 根据 .mcp.json 配置 MCP 服务并启动 Claude
• 在开发期间启用热重载

.mcp.json 配置：

{
  "mcpServers": {
    "whisper": {
      "command": "uv",
      "args": ["run", "mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "AUDIO_FILES_PATH": "${AUDIO_FILES_PATH}"
      }
    }
  }
}

提供的 MCP 工具

音频文件管理

• list_audio_files - 列出音频文件，并提供全面的筛选和排序选项：
  • 根据文件名的正则表达式匹配进行筛选
  • 根据文件大小、时长、修改时间或格式进行筛选
  • 按名称、大小、时长、修改时间或格式排序
  • 返回包含完整元数据、类型安全的 FilePathSupportParams
• get_latest_audio - 获取最近修改的音频文件，并提供模型支持信息

音频处理

• convert_audio - 将音频文件转换为支持的格式（mp3 或 wav）
  • 返回包含输出路径的 AudioProcessingResult
• compress_audio - 压缩超出大小限制的音频文件
  • 返回包含输出路径的 AudioProcessingResult

转录

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

  • 支持 whisper-1、gpt-4o-transcribe 和 gpt-4o-mini-transcribe
  • 支持使用自定义提示词引导转录
  • 可选的时间戳粒度，支持词级和片段级计时
  • 支持选择 JSON 响应格式
  • 返回包含文本、用量数据和可选时间戳的 TranscriptionResult

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

  • 支持 gpt-4o-audio-preview（推荐）和带日期的版本
  • 注意：gpt-4o-mini-audio-preview 在音频聊天方面存在限制，因此不推荐使用
  • 支持自定义系统提示词和用户提示词
  • 针对音频内容提供对话式回复
  • 返回包含回复文本的 ChatResult

• transcribe_with_enhancement - 使用专用模板增强转录：

  • detailed - 包含语气、情绪和背景细节
  • storytelling - 将转录文本转换为叙事形式
  • professional - 生成正式、适合商务场景的转录文本
  • analytical - 添加对说话模式和要点的分析
  • 返回包含增强结果的 TranscriptionResult

文本转语音

• create_audio - 使用 OpenAI 的 TTS API 生成文本转语音音频：
  • 支持 gpt-4o-mini-tts（优先使用）和其他语音模型
  • 支持多种语音选项（alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar）
  • 支持调整语速和设置自定义指令
  • 支持自定义输出文件路径
  • 可处理任意长度的文本，并自动拆分和合并音频片段
  • 返回包含输出路径的 TTSResult

支持的音频格式

**注意：**超过 25MB 的文件会自动压缩，以满足 API 限制。

Claude 使用示例

Claude, please transcribe my latest audio file with detailed insights.

Claude, list all my audio files that are longer than 5 minutes and were created after January 1st, 2024, sorted by size.

Claude, find all MP3 files with "interview" in the filename and create professional transcripts for each one.

Claude, create audio with this script: "Welcome to our podcast! Today we'll be discussing artificial intelligence trends in 2025." Use the shimmer voice.

在 Claude Desktop 中配置

在生产环境中使用 Claude Desktop（而非本地开发）时，请将以下内容添加到你的 claude_desktop_config.json：

UVX

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

推荐（仅限 Mac OS）

• 安装 Omi 屏幕录制器（免费）
• 将 AUDIO_FILES_PATH 设置为 /Users/<user>/Movies/Omi Screen Recorder，并将 <user> 替换为你的用户名
• 使用该应用录制音频时，可以通过 Claude 并行转录多个文件

开发

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

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Format code
uv run ruff format src

# Lint code
uv run ruff check src

# Run type checking (strict mode)
uv run mypy --strict src

# Run the pre-commit hooks
pre-commit run --all-files

CI/CD 工作流

本项目使用 GitHub Actions 实现 CI/CD：

1. Lint 和类型检查：使用 ruff 和严格的 mypy 类型检查来确保代码质量
2. 测试：在多个 Python 版本（3.10、3.11、3.12、3.13、3.14、3.14t）上运行测试
3. 发布与分发：采用双触发工作流，灵活管理发布

注意： Python 3.14t 是用于测试真正并行性的无 GIL 自由线程构建版本。

创建新版本

发布工作流支持两种方式：

选项 1：自动发布（推荐）

推送标签即可自动创建版本并发布到 PyPI：

# 1. Update version in pyproject.toml
# Edit the version field manually, e.g., "1.0.0" -> "1.1.0"

# 2. Update __version__ in src/mcp_server_whisper/__init__.py to match

# 3. Update the lock file
uv lock

# 4. Commit the version bump
git add pyproject.toml src/mcp_server_whisper/__init__.py uv.lock
git commit -m "chore: bump version to 1.1.0"

# 5. Create and push the version tag
git tag v1.1.0
git push origin main
git push origin v1.1.0

此操作将：

• 验证标签版本是否与 pyproject.toml 相符
• 构建软件包
• 创建附带自动生成说明的 GitHub 版本
• 自动发布到 PyPI

选项 2：手动发布

通过 GitHub 界面手动创建版本，然后可选择是否发布：

1. 前往 GitHub 上的 Releases
2. 点击“Draft a new release”
3. 创建新标签或选择现有标签
4. 填写版本详情
5. 点击“Publish release”

发布版本后，工作流将自动发布到 PyPI。你也可以创建草稿版本，延迟发布。

API 设计理念

MCP Server Whisper 采用扁平、类型安全的 API 设计，针对 MCP 客户端进行了优化：

• 扁平参数：所有工具都接受扁平参数，而非嵌套对象，让调用更简单直观
• 类型安全的响应：每个工具都返回强类型的 Pydantic 模型（TranscriptionResult、ChatResult、AudioProcessingResult、TTSResult）
• 单项操作：一次调用处理一个文件，由 MCP 协议原生处理并行性
• 按文件处理错误：失败仅影响单个操作，不会波及整个批次
• 自描述：类型提示可在 IDE 和 AI 模型中提供自动补全和验证

这种设计大幅降低了 AI 助手正确使用工具并可靠处理结果的难度。

工作原理

如需了解详细架构信息，请参阅架构文档。

MCP Server Whisper 基于 Model Context Protocol 构建，该协议规范了 AI 模型与外部工具及数据源的交互方式。该服务：

1. 提供音频处理能力：通过标准化的 MCP 工具接口和扁平、类型安全的 API 实现
2. 实现并行处理：使用 anyio 结构化并发；MCP 客户端原生处理并行性
3. 管理文件操作：处理检测、验证、转换和压缩
4. 提供丰富的转录功能：通过不同的 OpenAI 模型和增强模板实现
5. 优化性能：通过缓存机制处理重复操作
6. 确保类型安全：所有响应均使用 Pydantic 模型进行验证并提供 IDE 支持

底层使用：

• pydub 用于音频文件处理（Python 3.13 及更高版本使用 audioop-lts）
• anyio 用于结构化并发和任务组管理
• aioresult 用于收集并行任务组的结果
• 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 文件。

致谢

• Model Context Protocol (MCP) - 感谢其提供协议规范
• pydub - 感谢其提供音频处理功能
• OpenAI Whisper - 感谢其提供音频转录功能
• FastMCP - 感谢其提供 MCP 服务实现
• Anthropic Claude - 感谢其提供自然语言交互功能
• MCP Review - 此 MCP 服务已通过 MCP Review 认证