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