Whisper Transcribe

whisper-transcribe-mcp

使用 faster-whisper（本地、免费、离线）或 OpenAI Whisper API（云端，需要 API 密钥）进行音频转录的 MCP 服务。支持在 macOS、Windows 和 Linux 上使用 Claude Desktop 和 Claude Code。

---

前置条件

macOS

选项 A — uv（推荐）：

brew install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

选项 B — Python： macOS 12.3+ 已内置 Python 3.10+。你也可以使用 brew install python 安装。

---

Windows

选项 A — uv（推荐）：

winget install astral-sh.uv

或者从 astral.sh/uv 下载安装程序。

选项 B — Python： 从 python.org 下载 Python 3.10+。安装时，勾选 “Add Python to PATH”。

无需安装 ffmpeg 或任何编译器 — 所有内容都已打包在此软件包中。

---

Linux

选项 A — uv（推荐）：

curl -LsSf https://astral.sh/uv/install.sh | sh

选项 B — Python：

# Debian/Ubuntu
sudo apt install python3.12 python3.12-venv

# Fedora
sudo dnf install python3.12

# Arch
sudo pacman -S python

无需其他系统依赖项。

---

安装

选项 A — uvx（推荐，无需永久安装）

uvx 会自动在隔离环境中下载并安装软件包。只需安装 uv 即可。

# Local backend:
uvx "whisper-transcribe-mcp[local]"

# OpenAI backend:
uvx "whisper-transcribe-mcp[openai]"

# Both backends:
uvx "whisper-transcribe-mcp[all]"

选项 B — pip

# Local backend:
pip install "whisper-transcribe-mcp[local]"

# OpenAI backend:
pip install "whisper-transcribe-mcp[openai]"

# Both backends:
pip install "whisper-transcribe-mcp[all]"

---

使用场景

场景 1 — 仅使用本地后端（免费，可离线使用）

使用 faster-whisper 在本地进行转录。首次使用时会从 HuggingFace 下载模型（base 约为 74MB），并将其缓存。

安装：

pip install "whisper-transcribe-mcp[local]"

环境变量：

WHISPER_MODEL=base   # or tiny, small, medium, large-v3

---

场景 2 — 仅使用 OpenAI 后端（准确度最高，需要 API 密钥）

使用 OpenAI 的 whisper-1 模型。需要 API 密钥和互联网连接。不会下载本地模型。

安装：

pip install "whisper-transcribe-mcp[openai]"

环境变量：

OPENAI_API_KEY=sk-...

---

场景 3 — 同时使用两个后端（存在密钥时使用 OpenAI，否则回退到本地）

如果设置了 OPENAI_API_KEY，则会自动使用 OpenAI。否则会回退到本地 faster-whisper。

安装：

pip install "whisper-transcribe-mcp[all]"

---

配置

Claude Desktop

各操作系统的配置文件位置：

操作系统	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

在 "mcpServers" 中添加条目：

Windows 注意事项： Claude Desktop 在受限环境中运行，可能无法在 PATH 中找到 uvx，并且可能使用 ctranslate2（faster-whisper 的依赖项）尚未提供预编译 wheel 的 Python 版本（例如 3.14）。需要进行以下两项修复：

1. 使用 uvx.exe 的完整路径，而不是仅写 uvx。在 PowerShell 中运行 where.exe uvx 查找它（通常位于 C:\Users\<YourUser>\.local\bin\uvx.exe）。
2. 使用 --python 3.12 标志指定 Python 3.12，以确保使用兼容的 wheel。

场景 1 — 本地：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

场景 2 — OpenAI：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[openai]"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[openai]"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

场景 3 — 两者（设置密钥时优先使用 OpenAI）：

macOS / Linux：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[all]"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
      "args": ["--python", "3.12", "whisper-transcribe-mcp[all]"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

编辑文件后，重启 Claude Desktop。

---

Claude Code

在 macOS、Windows 和 Linux 上的使用方式相同。需要安装 uv。

Claude Code 配置文件位置：

OS	全局	按项目
macOS / Linux	~/.claude.json	.claude/settings.json（项目根目录）
Windows	C:\Users\<user>\.claude.json	.claude\settings.json（项目根目录）

添加服务最简单的方式是使用 Claude Code CLI，它会自动更新配置文件：

# Case 1 — Local:
claude mcp add whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"

# Case 2 — OpenAI:
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... -- "whisper-transcribe-mcp[openai]"

# Case 3 — Both (OpenAI with local fallback):
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... --env WHISPER_MODEL=base -- "whisper-transcribe-mcp[all]"

Windows + [all]： 在包名称前添加 --python 3.12，以避免 ctranslate2 wheel 问题。直接编辑 ~/.claude.json，并使用 "args": ["--python", "3.12", "whisper-transcribe-mcp[all]"]。

要全局添加（在所有项目中可用），请使用 --scope user：

claude mcp add --scope user whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"

或者直接编辑 ~/.claude.json，并在 "mcpServers" 中添加：

{
  "mcpServers": {
    "whisper-transcribe": {
      "command": "uvx",
      "args": ["whisper-transcribe-mcp[local]"],
      "env": {
        "WHISPER_MODEL": "base"
      }
    }
  }
}

---

环境变量

变量	默认值	描述
WHISPER_MODEL	base	本地模型大小：tiny、base、small、medium、large-v3
OPENAI_API_KEY	—	如果已设置，则启用 OpenAI 后端，而非本地后端
WHISPER_POST_PROCESS_MODEL	gpt-5.4-nano	当 post_process=true 时使用的 OpenAI 聊天模型

后端选择与回退（仅适用于 [all]）

使用 [all] 安装时，启动时会选择后端：

• 已设置 OPENAI_API_KEY → 使用 OpenAI。如果 API 调用在运行时失败（网络错误、密钥无效、超出配额），服务会自动回退到本地 faster-whisper，并在响应中包含 "fallback_reason" 字段。
• 未设置 OPENAI_API_KEY → 直接使用本地 faster-whisper，不尝试回退。

---

安全与权限

服务在本地通过 stdio 运行，只需要其工具所需的访问权限：

访问权限	原因
文件系统读取	transcribe_file 会读取你传入的音频文件路径。
临时文件	transcribe_base64 会将解码后的音频写入私有临时文件，并始终将其删除。
网络	仅用于 OpenAI 后端／后处理，以及首次从 Hugging Face 下载本地模型。
环境变量	OPENAI_API_KEY、WHISPER_MODEL、WHISPER_POST_PROCESS_MODEL。

工具输入会在使用前进行验证：model_size 必须是已知的 Whisper 模型名称， language 必须是 ISO 639 代码，extension 必须是已知的音频格式。OpenAI 错误 会以简短摘要的形式返回（错误类型和 HTTP 状态）；完整消息会发送到 stderr。 版本发布通过 GitHub Actions、PyPI Trusted Publishing 和 PEP 740 来源证明 声明进行。

---

可用工具

transcribe_file

按路径转录音频文件（mp3、wav、m4a、ogg、flac、webm 等）。

参数：

• file_path（必填）：音频文件的绝对路径
• language（可选）：语言代码（es、en、fr 等）。如果未提供，则自动检测。
• model_size（可选）：本地模型大小。使用 OpenAI 后端时会忽略。
• post_process（可选，默认 false）：如果为 true，则通过 GPT-4.1 对转录文本进行后处理，以修正拼写、语法和标点。需要 openai 包（[openai] 或 [all]）。
• post_process_prompt（可选）：用于 GPT 后处理的自定义系统提示词。可提供特定领域的上下文、专有名词或 Whisper 可能拼错的产品名称。如果未提供，则使用通用的校正提示词。

响应（不进行后处理）：

{
  "text": "Full transcription...",
  "language": "en",
  "language_probability": 0.99,
  "segments": [
    { "start": 0.0, "end": 4.2, "text": "First segment..." }
  ],
  "backend": "local",
  "model": "base"
}

响应（使用 post_process: true）：

{
  "text": "Corrected transcription...",
  "raw_text": "Original transcription from Whisper...",
  "post_process_model": "gpt-4.1",
  "language": "en",
  "language_probability": 0.99,
  "segments": [...],
  "backend": "local",
  "model": "base"
}

如果后处理失败，text 会保留原始转录文本，并添加 post_process_error 字段。

---

transcribe_base64

转录以 Base64 编码字符串提供的音频。适用于程序化集成。

参数：

• audio_base64（必填）：Base64 编码的音频数据
• extension（可选，默认值为 mp3）：文件扩展名（mp3、wav、ogg 等）
• language（可选）：语言代码
• model_size（可选）：本地模型大小
• post_process（可选，默认值为 false）：与 transcribe_file 中的参数相同。
• post_process_prompt（可选）：与 transcribe_file 中的参数相同。

---

list_models

显示当前后端配置、可用的本地模型以及用于后处理的 GPT 模型。

---

本地模型大小

模型	大小	相对速度	说明
tiny	39 MB	~32x	速度最快，准确度最低
base	74 MB	~16x	均衡之选（默认）
small	244 MB	~6x	准确度更高
medium	769 MB	~2x	准确度高
large-v3	1.5 GB	~1x	准确度最高，速度最慢

首次使用时会自动从 HuggingFace 下载模型，并在本地缓存。

---

故障排除

Claude Desktop 在 Windows 上无法加载 MCP

现象： 服务启动失败，并出现类似以下内容的依赖解析错误：

ctranslate2>=4.6.1 has no wheels with a matching platform tag (e.g., `win32`)
hint: You require CPython 3.14 (`cp314`), but we only found wheels for `ctranslate2` with: `cp39`, `cp310`, `cp311`, `cp312`, `cp313`

原因： 两个问题叠加所致：

1. Claude Desktop 的 PATH 不包含用户本地的 bin 目录，因此必须使用 uvx 的完整路径。
2. Claude Desktop 的 uvx 可能会选择某个 Python 版本（例如 3.14），而 faster-whisper 的原生依赖 ctranslate2 尚未提供适用于 Windows 的预编译 wheel。

解决方法： 使用 uvx.exe 的完整路径，并明确指定 Python 3.12：

"whisper-transcribe": {
  "command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
  "args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
  "env": { "WHISPER_MODEL": "base" }
}

要查找 uvx.exe 的确切路径，请在 PowerShell 中运行：

where.exe uvx

在 Claude Desktop 中转录音频文件

现象： Claude Desktop 无法转录上传的音频文件。它可能会尝试将文件读取为 Base64 并传给 transcribe_base64；对于大于约 50 KB 的文件，随后会失败或卡住。

原因： Claude Desktop 在沙盒化的 Linux 容器中运行。使用附件按钮上传文件时，文件会存储在类似 /mnt/user-data/uploads/audio.mp3 的路径中，也就是容器内。MCP 服务运行在你的 Windows 计算机上，无法访问容器中的该路径。Claude 采用的后备方案是将文件编码为 Base64 并传给 transcribe_base64，但实际使用中会失败，因为即使很小的音频文件也会生成数百 KB 的 Base64 文本，在发起工具调用前就会溢出上下文窗口。

解决方法： 请勿使用附件按钮上传音频文件。应将文件放在 Windows 文件系统中的任意位置，并在消息中直接引用其路径：

"转录此文件：C:\Users\YourUser\Downloads\audio.mp3"

MCP 服务会直接从 Windows 读取文件，并将其发送到转录后端。只要文件大小不超过 Whisper API 的限制（25 MB），无论大小均可使用此方法。

---

开发

此项目使用 uv 创建可复现的开发环境：

uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv run pre-commit install

有关贡献工作流，请参阅 CONTRIBUTING.md。

分发与发布

此软件包通过 PyPI 分发，并通过 server.json 提供信息以供 官方 MCP Registry 使用。版本标签会通过 GitHub OIDC 发布到这两个平台，无需长期有效的发布令牌。有关发布检查清单和一次性仓库设置，请参阅 docs/publishing.md。

Registry 条目描述的是基础 PyPI 软件包。请从上文的安装示例中选择 [local]、[openai] 或 [all] 额外依赖，以安装所需的转录后端。

---

许可证

MIT — 请参阅 LICENSE