STARWARCLOUD STARWAR.AI
返回市场
MCP服务器低语

MCP服务器低语

作者：arcaputo341 星标更新：2025-10-17
安装使用来源：spider==github.com

项目介绍

MCP Server Whisper

<div align="center">

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

PyPI 版本 MIT 许可证 Python 3.10+ CI 状态 用uv构建

</div>

概述

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

关键特性：

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

注意：此项目是未经官方授权的，不隶属于、未得到OpenAI的认可或赞助。它提供了一个与OpenAI公开API接口的模型上下文协议界面。

安装

# 克隆仓库
git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

# 使用uv
uv sync

# 设置预提交钩子
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配置启动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

支持的音频格式

模型支持的格式
转录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和模式及格式过滤器搜索文件
  2. 并行调用多次transcribe_with_enhancement工具（MCP原生支持并行处理）
  3. 每次调用使用enhancement_type: "professional"并返回类型化的TranscriptionResult
  4. 返回所有转录结果，带有完整的元数据，格式良好
</details> <details> <summary>生成文本到语音音频</summary> 
Claude，使用这个脚本创建音频：“欢迎来到我们的播客！今天我们将讨论2025年人工智能趋势。”使用shimmer声音。

Claude将：

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

配置与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）

  • 安装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 run --all-files

CI/CD工作流

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

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

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

创建新版本

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

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

推送标签以自动创建发布并发布到PyPI：

# 1. 更新pyproject.toml中的版本
# 手动编辑版本字段，例如，“1.0.0” -> “1.1.0”

# 2. 更新src/mcp_server_whisper/__init__.py中的__version__以匹配

# 3. 更新锁文件
uv lock

# 4. 提交版本更新
git add pyproject.toml src/mcp_server_whisper/__init__.py uv.lock
git commit -m "chore: bump version to 1.1.0"

# 5. 创建并推送版本标签
git tag v1.1.0
git push origin main
git push origin v1.1.0

这将：

  • 验证标签版本是否与pyproject.toml匹配
  • 构建包
  • 创建带有自动生成说明的GitHub发布
  • 自动发布到PyPI

选项2：手动发布

通过GitHub UI手动创建发布，然后可选地发布：

  1. 转到GitHub上的发布页面
  2. 点击“起草新发布”
  3. 创建新标签或选择现有标签
  4. 填写发布详情
  5. 点击“发布”

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

API设计哲学

MCP Server Whisper遵循一种扁平、类型安全的API设计，优化了MCP客户端的使用：

  • 扁平参数：所有工具接受扁平参数而不是嵌套对象，以便更简单、直观的调用
  • 类型安全响应：每个工具返回一个强类型的Pydantic模型（TranscriptionResult、ChatResult、AudioProcessingResult、TTSResult）
  • 单个项操作：一次调用处理一个文件，MCP协议原生处理并行处理
  • 单个操作错误处理：失败隔离到单独的操作，而不是整个批次
  • 自我文档化：类型提示提供IDE和AI模型中的自动完成和验证

这种设计使得AI助手更容易正确使用工具并可靠地处理结果。

工作原理

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

MCP Server Whisper基于模型上下文协议构建，该协议标准化了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. 分叉仓库
  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 '添加一些惊人的功能'）
  6. 推送到分支（git push origin feature/amazing-feature）
  7. 打开拉取请求

许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

致谢

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