内容
# whisper-telegram-mcp
> 通过 Telegram 实现双向语音功能，用于 Claude
[](https://github.com/abid-mahdi/whisper-telegram-mcp/actions)
[](https://pypi.org/project/whisper-telegram-mcp/)
[](https://pypi.org/project/whisper-telegram-mcp/)
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://ko-fi.com/abidmahdi)
一个 [MCP](https://modelcontextprotocol.io) 服务器，通过 Telegram 为 Claude 提供双向语音功能：使用 Whisper 转录传入的语音消息，并用合成语音回复。适用于 Claude Desktop、Claude Code 和任何 MCP 兼容的客户端。
## 功能
- **转录本地音频文件** -- OGG、WAV、MP3、FLAC 等
- **转录 Telegram 语音消息** -- 传入 `file_id`，返回文本
- **将文本转为语音笔记** -- 合成语音并作为 OGG 发送（在 Telegram 中播放为语音笔记）
- **两种转录后端** -- 本地 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)（免费、私有）或 OpenAI Whisper API（云端）
- **自动模式** -- 优先使用本地后端，失败时 fallback 到 OpenAI
- **语言检测** -- 自动或指定 ISO-639-1 代码
- **词级时间戳** -- 可选的细粒度计时
## 前置条件
| 功能 | 要求 |
|---------|-------------|
| 转录（本地） | 无 -- faster-whisper 通过 `[local]` extras 捆绑 |
| 转录（云端） | `OPENAI_API_KEY` 环境变量 |
| 语音回复 -- Kokoro（最佳质量） | **Docker** -- 运行 `docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest` |
| 语音回复 -- OpenAI TTS（fallback） | `OPENAI_API_KEY` 环境变量 |
| 语音回复 -- macOS say（最后的手段） | 仅限 Mac，无需设置 |
> **Kokoro 需要 Docker.** 如果 Docker 未运行，语音回复将自动 fallback 到 OpenAI TTS 或 macOS `say`。
## 快速开始
### 30 秒设置 Claude Code
最快的开始方式 -- 只需告诉 Claude Code 为您设置：
1. 将以下内容添加到您的 `.mcp.json`（Claude Code）或 `claude_desktop_config.json`（Claude Desktop）：
```json
{
"mcpServers": {
"whisper-telegram-mcp": {
"command": "uvx",
"args": ["whisper-telegram-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
```
2. 重启 Claude 并说：*"设置我的 Telegram 机器人用于语音转录"* -- Claude 将引导您创建机器人并配置所有内容。
### 使用 `uvx` 单命令
```bash
uvx whisper-telegram-mcp
```
无需安装 -- `uvx` 处理所有事情。
### 或使用 pip 安装
```bash
pip install "whisper-telegram-mcp[all]"
whisper-telegram-mcp
```
## Telegram 机器人设置
1. 打开 Telegram 并与 [@BotFather](https://t.me/BotFather) 消息
2. 发送 `/newbot` 并按照提示创建机器人
3. 复制令牌（看起来像 `1234567890:ABCdef...`）
4. 将 `TELEGRAM_BOT_TOKEN` 添加到您的 MCP 配置环境变量（见下文）
5. 消息您的机器人以开始 -- 它只会对已批准的用户做出响应
> Claude Telegram 插件处理访问控制。参见其文档了解配对/允许列表设置。
## 集成
### Claude Desktop
将以下内容添加到您的 Claude Desktop 配置文件 (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"whisper-telegram-mcp": {
"command": "uvx",
"args": ["whisper-telegram-mcp"],
"env": {
"WHISPER_MODEL": "base",
"WHISPER_BACKEND": "auto",
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
```
### Claude Code
将以下内容添加到您的项目 `.mcp.json`：
```json
{
"mcpServers": {
"whisper-telegram-mcp": {
"command": "uvx",
"args": ["whisper-telegram-mcp"],
"env": {
"WHISPER_MODEL": "base",
"WHISPER_BACKEND": "auto",
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `transcribe_audio` | 将本地音频文件（OGG、WAV、MP3 等）转录为文本 |
| `transcribe_telegram_voice` | 下载并转录 Telegram 语音消息，通过 `file_id` |
| `speak_text` | 将文本转换为语音 → OGG/Opus 文件（在 Telegram 中播放为语音笔记） |
| `list_models` | 列出可用的 Whisper 模型大小，附带速度/精度信息 |
| `check_backends` | 检查哪些后端（本地/OpenAI）可用且已配置 |
### `transcribe_audio`
```
file_path: str # 音频文件的绝对路径
language: str | None # ISO-639-1 代码（例如 "en"），None = 自动检测
word_timestamps: bool # 包括词级时间戳（默认：false）
```
### `transcribe_telegram_voice`
```
file_id: str # Telegram 语音消息的 file_id
bot_token: str | None # 机器人令牌（fallback 到 TELEGRAM_BOT_TOKEN 环境变量）
language: str | None # ISO-639-1 代码，None = 自动检测
word_timestamps: bool # 包括词级时间戳（默认：false）
```
### `speak_text`
将文本转换为 OGG/Opus 音频文件。自动选择最佳的 TTS 后端。
```
text: str # 要合成的文本
voice: str # 语音名称（默认："af_sky"）
output_path: str|None # 输出 .ogg 文件的可选路径
```
**TTS 后端（按优先级顺序）：**
| 后端 | 成本 | 质量 | 设置 |
|---------|------|---------|-------|
| **Kokoro**（本地） | 免费 | 自然、高质量 | 手动启动（见下文） |
| **OpenAI TTS**（云端） | ~$0.015/1k 字符 | 高质量 | `OPENAI_API_KEY` 环境变量 |
| **macOS say**（fallback） | 免费 | 机器人般 | 仅限 Mac，无需设置 |
在 `auto` 模式（默认）下，服务器优先尝试 Kokoro，然后是 OpenAI，最后是 macOS `say`。通过 `TTS_BACKEND` 环境变量进行配置。
**启动 Kokoro 本地：**
Kokoro FastAPI 不在 PyPI 上 -- 在运行 MCP 服务器之前启动：
```bash
# Docker（最简单，推荐）
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest
# Apple Silicon（GPU 加速）
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu-mac:latest
# 从源码
git clone https://github.com/remsky/Kokoro-FastAPI && cd Kokoro-FastAPI && ./start-cpu.sh
```
一旦运行，MCP 服务器就会自动检测到 `http://127.0.0.1:8880/v1`。可以通过 `KOKORO_BASE_URL` 环境变量覆盖。
**Kokoro 语音（主要）：**
| 语音 | 口音 | 风格 |
|-------|--------|-------|
| `af_sky` | 美国 | 女性（默认） |
| `af_bella` | 美国 | 女性 |
| `af_sarah` | 美国 | 女性 |
| `af_nicole` | 美国 | 女性 |
| `am_adam` | 美国 | 男性 |
| `am_michael` | 美国 | 男性 |
| `bf_emma` | 英国 | 女性 |
| `bf_isabella` | 英国 | 女性 |
| `bm_george` | 英国 | 男性 |
| `bm_lewis` | 英国 | 男性 |
**OpenAI 语音（fallback）：**
| 语音 | 风格 |
|-------|-------|
| `alloy` | 中性 |
| `echo` | 男性 |
| `fable` | 叙事 |
| `onyx` | 男性（深沉） |
| `nova` | 女性 |
| `shimmer` | 女性（柔和） |
当 fallback 时，Kokoro 语音名称会自动映射到最接近的 OpenAI 或 macOS 等效语音。
**返回：**
```json
{
"file_path": "/tmp/tmpXXX.ogg",
"size_bytes": 16555,
"backend": "kokoro",
"voice": "af_sky",
"success": true,
"error": null
}
```
将返回的 `file_path` 作为 Telegram 附件发送，它将显示为原生语音笔记。
### 转录响应格式
所有转录工具返回：
```json
{
"text": "Hello, this is a voice message.",
"language": "en",
"language_probability": 0.98,
"duration": 3.5,
"segments": [
{"start": 0.0, "end": 3.5, "text": "Hello, this is a voice message."}
],
"backend": "local",
"success": true,
"error": null
}
```
## 配置
所有配置均通过环境变量进行：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `WHISPER_BACKEND` | `auto` | `auto`、`local` 或 `openai` |
| `WHISPER_MODEL` | `base` | Whisper 模型大小（见下文） |
| `OPENAI_API_KEY` | -- | `openai` 转录和 TTS 后端所需 |
| `TELEGRAM_BOT_TOKEN` | -- | `transcribe_telegram_voice` 所需 |
| `WHISPER_LANGUAGE` | 自动检测 | ISO-639-1 语言代码 |
| `TTS_BACKEND` | `auto` | `auto`、`kokoro`、`openai` 或 `macos` |
| `TTS_VOICE` | `af_sky` | `speak_text` 的默认语音（Kokoro 语音名称） |
| `KOKORO_BASE_URL` | `http://127.0.0.1:8880/v1` | Kokoro FastAPI 基本 URL |
## 工作原理
```
MCP 客户端（Claude）
|
[MCP stdio]
|
whisper-telegram-mcp
/ | \
/ | \
transcribe_audio transcribe_ speak_text
telegram_voice |
| | auto_tts()
| [Bot API DL] / | \
+--------+------+ Kokoro OpenAI macOS
| （本地）（云端）（say）
auto_transcribe() |
/ \ .ogg 文件
LocalBackend OpenAIBackend
（faster-whisper）（Whisper API）
```
1. Claude 通过 MCP（stdio 传输）发送工具调用
2. 对于 Telegram 语音消息，通过 Bot API 下载文件
3. `auto_transcribe()` 选择最佳的转录后端
4. `auto_tts()` 选择最佳的 TTS 后端（Kokoro -> OpenAI -> macOS）
5. 结果以结构化 JSON 返回
## 本地 vs OpenAI
| | 本地（faster-whisper） | OpenAI API |
|---|---|---|
| **成本** | 免费 | $0.006/min |
| **隐私** | 所有数据保留在设备上 | 音频发送到 OpenAI |
| **速度** | ~1-10s 取决于模型 | ~1-3s |
| **设置** | 自动（首次使用时下载模型） | 需要 `OPENAI_API_KEY` |
| **准确性** | 优秀（使用 `base` 或更大模型） | 优秀 |
| **离线** | 是 | 否 |
### 模型大小
| 模型 | 参数 | 速度 | 准确性 | VRAM |
|-------|-----------|-------|----------|------|
| `tiny` | 39M | 最快 | 最低 | ~1GB |
| `base` | 74M | 快速 | 良好 | ~1GB |
| `small` | 244M | 中等 | 更好 | ~2GB |
| `medium` | 769M | 慢 | 高 | ~5GB |
| `large-v3` | 1550M | 最慢 | 最高 | ~10GB |
| `turbo` | ~800M | 快速 | 高 | ~6GB |
仅限英语变体（`tiny.en`、`base.en`、`small.en`、`medium.en`）对英语略微更准确。
## 隐私与数据
- **本地后端（faster-whisper）**：音频保留在您的设备上。没有任何数据离开您的机器。
- **OpenAI 后端**：音频发送到 OpenAI API，遵循其 [数据保留政策](https://platform.openai.com/docs/guides/privacy)
- **临时文件**：从 Telegram 下载的音频写入 `/tmp` 并在转录后立即删除
- **日志**：仅输出到 stderr -- 绝不会记录任何音频内容或凭证
## 开发
```bash
git clone https://github.com/abid-mahdi/whisper-telegram-mcp.git
cd whisper-telegram-mcp
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# 运行单元测试
pytest tests/ -v -m "not integration"
# 运行集成测试（下载 ~150MB 模型）
pytest tests/ -m integration -v
# 运行覆盖率
pytest tests/ --cov=src/whisper_telegram_mcp --cov-report=term-missing
```
### MCP 检验
```bash
uvx mcp dev src/whisper_telegram_mcp/server.py
```
## 贡献
1. Fork 仓库
2. 创建功能分支（`git checkout -b feat/amazing-feature`）
3. 运行测试（`pytest tests/ -v -m "not integration"`）
4. 使用约定提交（`feat:`、`fix:`、`docs:`等）
5. 打开拉取请求
## 许可证
[MIT](LICENSE)
