Whisper Telegram MCP

🎙️ whisper-telegram-mcp

转录与语音合成 —— 通过 Telegram 为 Claude 提供双向语音能力

一个 MCP 服务器，通过 Telegram 赋予 Claude 双向语音能力：使用 Whisper 转录接收到的语音消息，并以合成语音进行回复。兼容 Claude Desktop、Claude Code 以及任何支持 MCP 的客户端。

🚀 快速开始

⚡ 使用 Claude Code 在 30 秒内完成配置

这是最快的上手方式 —— 只需告诉 Claude Code 帮你配置即可：

1. 添加到 .mcp.json（Claude Code）或 claude_desktop_config.json（Claude Desktop）：

{
  "mcpServers": {
    "whisper-telegram-mcp": {
      "command": "uvx",
      "args": ["whisper-telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

2. 重启 Claude 并说："Set up my Telegram bot for voice transcription" —— Claude 会引导你通过 BotFather 创建机器人并完成全部配置。

📦 使用 uvx 一键运行

uvx whisper-telegram-mcp

无需安装 —— uvx 会处理一切。

🐍 或使用 pip 安装

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

✨ 主要特性

• 转录本地音频文件 —— 支持 OGG、WAV、MP3、FLAC 等多种格式
• 转录 Telegram 语音消息 —— 传入 file_id，返回文本
• 将文本合成为语音消息 —— 合成语音并以 OGG 格式返回（在 Telegram 中显示为原生语音消息）
• 两种转录后端 —— 本地 faster-whisper（免费、隐私安全）或 OpenAI Whisper API（云端）
• 自动模式（auto） —— 优先尝试本地后端，失败时回退到 OpenAI
• 语言检测 —— 自动检测，或指定 ISO-639-1 语言代码
• 词级时间戳 —— 可选的细粒度计时

📋 前提条件

⚠️ 重要提示

Kokoro 依赖 Docker。 如果 Docker 未运行，语音回复会自动回退到 OpenAI TTS 或 macOS say。

🤖 Telegram 机器人配置

1. 打开 Telegram，向 @BotFather 发送消息
2. 发送 /newbot 并按照提示创建机器人
3. 复制 token（形如 1234567890:ABCdef...）
4. 将 TELEGRAM_BOT_TOKEN 添加到 MCP 配置的环境变量中（见下文）
5. 向你的机器人发送消息即可开始 —— 它只会响应已授权的用户

💡 使用建议

Claude Telegram 插件负责访问控制。关于配对/白名单的设置，请参阅其官方文档。

🔌 集成配置

Claude Desktop

添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.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：

{
  "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

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 # 机器人 token（默认回退到 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 后端（按优先级排序）

在 auto 模式（默认）下，服务器会依次尝试 Kokoro、OpenAI、macOS say。可通过环境变量 TTS_BACKEND 进行配置。

🐳 在本地启动 Kokoro

Kokoro FastAPI 并未发布在 PyPI 上 —— 需要在启动 MCP 服务器之前手动启动：

# 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 语音（主要）

🎤 OpenAI 语音（回退方案）

回退时，Kokoro 的语音名称会自动映射到最接近的 OpenAI 或 macOS 语音。

📤 返回值

{
  "file_path": "/tmp/tmpXXX.ogg",
  "size_bytes": 16555,
  "backend": "kokoro",
  "voice": "af_sky",
  "success": true,
  "error": null
}

将返回的 file_path 作为 Telegram 附件发送，它便会以原生语音消息的形式呈现。

📄 转录响应格式

所有转录工具均返回以下格式：

{
  "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
}

⚙️ 配置项

所有配置均通过环境变量完成：

🔧 工作原理

                         MCP Client (Claude)
                              |
                         [MCP stdio]
                              |
                    whisper-telegram-mcp
                    /         |         \
                   /          |          \
      transcribe_audio  transcribe_     speak_text
                        telegram_voice      |
              |               |          auto_tts()
              |         [Bot API DL]    /    |    \
              +--------+------+     Kokoro OpenAI macOS
                       |            (local) (cloud) (say)
                 auto_transcribe()      |
                  /           \      .ogg file
           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 方案

📊 模型大小

纯英文变体（tiny.en、base.en、small.en、medium.en）在英文场景下准确率略高。

🔒 隐私与数据

• 本地后端（faster-whisper）：音频保留在你的设备上，任何数据都不会离开本机。
• OpenAI 后端：音频将发送至 OpenAI API，遵循其数据保留政策
• 临时文件：从 Telegram 下载的音频会写入 /tmp，并在转录完成后立即删除
• 日志：仅输出到 stderr —— 任何音频内容或凭据都不会被记录到日志

🧑💻 开发

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 Inspector

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. 使用 Conventional Commits 规范提交（feat:、fix:、docs: 等）
5. 提交 Pull Request

📄 许可证

MIT