MCP服务器低语
使用OpenAI的Whisper和GPT-4o模型进行高级音频转录和处理的模型上下文协议（MCP）服务器。
\[！警告\] 这个项目已经转移了。 主动开发已迁移到 TJC-LP/桑扎鲁。此存储库将不再维护并存档。请将您的依赖关系和问题更新到新的仓库。
概述
MCP Server Whisper提供了一种通过OpenAI最新的转录和语音服务处理音频文件的标准化方法。通过实施 模型上下文协议，它使像克劳德这样的人工智能助手能够与音频处理功能无缝交互。
主要特点：
- 🔍 高级文件搜索 具有正则表达式模式、文件元数据过滤和排序功能
- ⚡ 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 基于提供的文件 .env.example:
cp .env.example .env编辑 .env 根据您的实际值：
OPENAI_API_KEY=your_openai_api_key
AUDIO_FILES_PATH=/path/to/your/audio/files注： 环境变量必须在运行时可用。使用Claude进行本地开发时，请使用以下工具 dotenv-cli 加载它们（请参阅下面的用法部分）。
用法
与克劳德共同发展
该项目包括 .mcp.json 用于使用Claude进行本地开发的配置文件。要使用它：
- 确保您的
.env文件配置了所需的环境变量 - 加载环境变量后启动Claude：
bunx dotenv-cli -- claude这将：
- 从您的
.env文件 - 使用配置的MCP服务器启动Claude
.mcp.json - 在开发过程中启用热重新加载
这 .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 （首选）和其他语音模型 - 多种音色选项（合金、灰、民谣、珊瑚、回声、鼠尾草、微光、诗句、马林、雪松） - 速度调节和自定义说明 - 可自定义的输出文件路径 - 通过自动分割和连接音频片段来处理任何长度的文本 - 退货 TTSResult 带输出路径
支持的音频格式
| 型号 | 支持的格式 |
|---|---|
| 转录 | flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav、webm |
| 聊天 | mp3、wav |
注： 大于25MB的文件会自动压缩以满足API的限制。
Claude使用示例
Basic Audio Transcription
Claude, please transcribe my latest audio file with detailed insights.克劳德将自动：
- 使用查找最新音频文件
get_latest_audio - 确定合适的转录方法
- 使用以下方式处理文件
transcribe_with_enhancement使用“详细”模板 - 返回增强的转录
Advanced Audio File Search and Filtering
Claude, list all my audio files that are longer than 5 minutes and were created after January 1st, 2024, sorted by size.克劳德将：
- 将日期转换为时间戳
- 使用
list_audio_files使用适当的过滤器：
- min_duration_seconds: 300 （5分钟） - min_modified_time: - sort_by: "size"
- 返回具有综合元数据的匹配音频文件的排序列表
Batch Processing Multiple Files
Claude, find all MP3 files with "interview" in the filename and create professional transcripts for each one.克劳德将：
- 使用搜索文件
list_audio_files带有模式和格式过滤器 - 使多个并行
transcribe_with_enhancement工具调用（MCP本机处理并行性） - 每次通话使用
enhancement_type: "professional"并返回键入的TranscriptionResult - 在格式良好的输出中返回包含完整元数据的所有转录
Generating Text-to-Speech Audio
Claude, create audio with this script: "Welcome to our podcast! Today we'll be discussing artificial intelligence trends in 2025." Use the shimmer voice.克劳德将：
- 使用
create_audio工具包括：
- text_prompt 包含脚本 - voice: "shimmer" - model: "gpt-4o-mini-tts" （默认高质量型号） - instructions: "Speak in an enthusiastic, podcast host style" （可选） - speed: 1.0 （默认，可以调整）
- 生成音频文件并将其保存到配置的音频目录
- 提供生成的音频文件的路径
使用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//Movies/Omi Screen Recorder并替换 `` 使用您的用户名 - 当您使用该应用程序录制音频时，您可以与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-filesCI/CD工作流程
该项目使用GitHub Actions for CI/CD：
- 棉绒和类型检查：通过ruff和严格的mypy类型检查确保代码质量
- 测试：在多个Python版本（3.10、3.11、3.12、3.13、3.14、3.14t）上运行测试
- 发布与发布：双触发工作流程，实现灵活的发布管理
注： 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 UI手动创建发布，然后可选择发布：
- 首选 发布 在GitHub上
- 点击“起草新版本”
- 创建新标签或选择现有标签
- 填写发布详细信息
- 点击“发布发布”
发布版本时，工作流将自动发布到PyPI。您还可以创建草稿发布以延迟发布。
API设计理念
MCP服务器耳语遵循 扁平、类型安全的API设计 针对MCP客户端进行了优化：
- 平淡的争论：所有工具都接受平面参数而不是嵌套对象，以实现更简单、更直观的调用
- 类型安全响应：每个工具都返回一个强类型的Pydantic模型(
TranscriptionResult,ChatResult,AudioProcessingResult,TTSResult) - 单项操作：一个调用处理一个文件，MCP协议本机处理并行性
- 每个文件错误处理：故障仅限于单个操作，而不是整个批次
- 自我记录：类型提示在IDE和AI模型中提供自动补全和验证
这种设计使AI助手更容易正确使用工具并可靠地处理结果。
运作原理
有关详细的体系结构信息，请参见 架构文档.
MCP Server Whisper基于模型上下文协议构建，该协议规范了人工智能模型与外部工具和数据源的交互方式。服务器：
- 展示音频处理能力：通过具有扁平、类型安全API的标准化MCP工具接口
- 实现并行处理：使用anyio结构化并发；MCP客户端以本机方式处理并行性
- 管理文件操作：处理检测、验证、转换和压缩
- 提供丰富的转录：通过不同的OpenAI模型和增强模板
- 优化性能：具有用于重复操作的缓存机制
- 确保类型安全：所有响应都使用Pydantic模型进行验证和IDE支持
在引擎盖下，它使用：
pydub用于音频文件操作（带audioop-lts适用于Python 3.13+）anyio用于结构化并发和任务组管理aioresult用于收集并行任务组的结果- OpenAI最新的转录模型（包括gpt-4o-transcript）
- OpenAI的GPT-4o音频模型可增强理解
- OpenAI的gpt-4o-mini-tts用于高质量语音合成
- FastMCP用于简化MCP服务器实施
- 整个代码库中的类型提示和严格的mypy验证
贡献
欢迎投稿！请按照以下步骤操作：
- 分叉存储库
- 为您的功能创建新分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试和linting(
uv run pytest && uv run ruff check src && uv run mypy --strict src) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- 模型上下文协议（MCP） -协议规范
- pydub -用于音频处理
- OpenAI耳语 -用于音频转录
- FastMCP -用于MCP服务器实施
- 安thropic克劳德 -用于自然语言交互
- MCP审查 -此MCP服务器已通过MCP Review认证
______________________________________________________________________
Made with ❤️ by Richie Caputo