whisper-telegram-mcp

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

一个 MCP 服务器，通过 Telegram 为 Claude 提供双向语音功能：使用 Whisper 转录收到的语音消息，并使用合成语音进行回复。适用于 Claude Desktop、Claude Code 以及任何兼容 MCP 的客户端。

功能特性

转录本地音频文件 -- 支持 OGG、WAV、MP3、FLAC 等格式
转录 Telegram 语音消息 -- 传入 file_id 即可获取文本
将文本转为语音笔记 -- 合成语音并以 OGG 格式发送（在 Telegram 中显示为语音笔记）
两种转录后端 -- 本地 faster-whisper（免费、私密）或 OpenAI Whisper API（云端）
自动模式 -- 优先尝试本地转录，失败后自动回退到 OpenAI
语言检测 -- 自动检测或指定 ISO-639-1 代码
词级时间戳 -- 可选的精细时间戳

前置要求

功能	要求
转录（本地）	无 — 通过 `[local]` 扩展包内置了 faster-whisper
转录（云端）	`OPENAI_API_KEY` 环境变量
语音回复 — Kokoro（最佳质量）	Docker — 运行 `docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest`
语音回复 — OpenAI TTS（回退）	`OPENAI_API_KEY` 环境变量
语音回复 — macOS say（最后手段）	仅限 Mac，无需设置

Kokoro 需要 Docker。 如果未运行 Docker，语音回复将自动回退到 OpenAI TTS 或 macOS 的 say 命令。

快速开始

使用 Claude Code 在 30 秒内完成设置

最快的入门方式 — 只需告诉 Claude Code 为你设置：

添加到你的 .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"
      }
    }
  }
}

重启 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

Telegram 机器人设置

打开 Telegram 并给 @BotFather 发消息
发送 /newbot 并按照提示创建机器人
复制 Token（格式如 1234567890:ABCdef...）
将 TELEGRAM_BOT_TOKEN 添加到你的 MCP 配置环境变量中（见下文）
给你的机器人发消息以开始 — 它只会响应已批准的用户

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`	将本地音频文件（OGG、WAV、MP3 等）转录为文本
`transcribe_telegram_voice`	通过 `file_id` 下载并转录 Telegram 语音消息
`speak_text`	将文本转换为语音 → OGG/Opus 文件（在 Telegram 中作为语音笔记播放）
`list_models`	列出可用的 Whisper 模型大小及其速度/准确度信息
`check_backends`	检查哪些后端（本地/OpenAI）可用并已配置

`transcribe_audio`

file_path: str        # Absolute path to audio file
language: str | None  # ISO-639-1 code (e.g. "en"), None = auto-detect
word_timestamps: bool # Include word-level timestamps (default: false)

`transcribe_telegram_voice`

file_id: str          # Telegram voice message file_id
bot_token: str | None # Bot token (falls back to TELEGRAM_BOT_TOKEN env var)
language: str | None  # ISO-639-1 code, None = auto-detect
word_timestamps: bool # Include word-level timestamps (default: false)

`speak_text`

将文本转换为 OGG/Opus 音频文件。自动选择最佳的可用 TTS 后端。

text: str             # Text to synthesise
voice: str            # Voice name (default: "af_sky")
output_path: str|None # Optional path for output .ogg file

TTS 后端（按优先级排序）：

后端	成本	质量	设置
Kokoro (本地)	免费	自然，高质量	手动启动（见下文）
OpenAI TTS (云端)	~$0.015/1k 字符	高质量	`OPENAI_API_KEY` 环境变量
macOS say (回退)	免费	机械感	仅限 Mac，无需设置

在 auto 模式（默认）下，服务器优先尝试 Kokoro，然后是 OpenAI，最后是 macOS say。可通过 TTS_BACKEND 环境变量进行配置。

在本地启动 Kokoro：

Kokoro FastAPI 不在 PyPI 上 — 请在运行 MCP 服务器之前启动它：

# Docker (simplest, recommended)
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# Apple Silicon (GPU-accelerated)
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu-mac:latest

# From source
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 语音（回退）：

语音	风格
`alloy`	中性
`echo`	男性
`fable`	叙述
`onyx`	深沉男性
`nova`	女性
`shimmer`	轻柔女性

当回退时，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
}

配置

所有配置均通过环境变量进行：

变量	默认值	描述
`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 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)

Claude 通过 MCP（stdio 传输）发送工具调用
对于 Telegram 语音消息，文件通过 Bot API 下载
auto_transcribe() 选择最佳的可用转录后端
auto_tts() 选择最佳的可用 TTS 后端（Kokoro -> OpenAI -> macOS）
结果以结构化 JSON 形式返回

本地 vs OpenAI

	本地 (faster-whisper)	OpenAI API
成本	免费	$0.006/分钟
隐私	所有数据保留在设备上	音频发送至 OpenAI
速度	~1-10秒（取决于模型）	~1-3秒
设置	自动（首次使用时下载模型）	需要 `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
临时文件：从 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]"

# Run unit tests
pytest tests/ -v -m "not integration"

# Run integration tests (downloads ~150MB model on first run)
pytest tests/ -m integration -v

# Run with coverage
pytest tests/ --cov=src/whisper_telegram_mcp --cov-report=term-missing

MCP Inspector

uvx mcp dev src/whisper_telegram_mcp/server.py

贡献

Fork 本仓库
创建功能分支 (git checkout -b feat/amazing-feature)
运行测试 (pytest tests/ -v -m "not integration")
使用规范化提交 (feat:, fix:, docs: 等)
提交 Pull Request

许可证

MIT

whisper-telegram-mcp

whisper-telegram-mcp

功能特性

前置要求

快速开始

使用 Claude Code 在 30 秒内完成设置

使用 `uvx` 一键运行

或使用 pip 安装

Telegram 机器人设置

集成

Claude Desktop

Claude Code

工具

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`

转录响应格式

配置

工作原理

本地 vs OpenAI

模型大小

隐私与数据

开发

MCP Inspector

贡献

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

whisper-telegram-mcp

功能特性

前置要求

快速开始

使用 Claude Code 在 30 秒内完成设置

使用 uvx 一键运行

或使用 pip 安装

Telegram 机器人设置

集成

Claude Desktop

Claude Code

工具

transcribe_audio

transcribe_telegram_voice

speak_text

转录响应格式

配置

工作原理

本地 vs OpenAI

模型大小

隐私与数据

开发

MCP Inspector

贡献

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

使用 `uvx` 一键运行

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`