Whisper Telegram MCP

密语电报mcp

转录和说话——克劳德通过Telegram的双向语音

  ](https://pypi.org/project/whisper-telegram-mcp/)    

Demo: send a voice note, get a voice reply

一 主控程序 通过Telegram为Claude提供双向语音功能的服务器：用Whisper转录传入的语音信息，并用合成语音回复。适用于Claude Desktop、Claude Code和任何兼容MCP的客户端。

它的作用

• 转录本地音频文件 --OGG、WAV、MP3、FLAC等
• 转录Telegram语音信息 --通过a file_id，取回文本
• 以语音笔记的形式朗读文本 --合成语音并作为OGG发送回来（在Telegram中作为语音备忘播放）
• 两个转录后端 --本地 更快的耳语 （免费，私人）或OpenAI Whisper API（云）
• 自动模式 --首先尝试本地，如果失败则回退到OpenAI
• 语言检测 --自动或指定ISO-639-1代码
• 字级时间戳 --可选的细粒度计时

先决条件

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

快速开始

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

最快的入门方法是告诉Claude Code为您设置：

1. 添加到您的 .mcp.json （克劳德代码）或 claude_desktop_config.json （克劳德桌面）：

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

1. 重新启动克劳德并说： *“设置我的Telegram机器人进行语音转录”* --Claude将指导您使用BotFather创建机器人并配置一切。

一个命令 uvx

uvx whisper-telegram-mcp

无需安装-- uvx 处理一切。

或使用pip安装

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

电报机器人设置

1. 打开电报和消息 @植物学家
2. 发送 /newbot 并按照提示创建bot
3. 复制令牌（看起来像 1234567890:ABCdef...)
4. 添加 TELEGRAM_BOT_TOKEN 到您的MCP配置环境（见下文）
5. 向您的机器人发送启动消息——它只会对批准的用户做出响应

Claude Telegram插件处理访问控制。有关配对/分配列表设置，请参阅其文档。

整合

克劳德桌面

添加到您的Claude桌面配置(~/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"
      }
    }
  }
}

克劳德代码

添加到您的项目 .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        # 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后端（按优先级顺序）：

在 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 有人是。

科科罗声音（主要）：

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)对于英语来说稍微准确一些。

隐私和数据

• 本地后端（更快的耳语）：音频保留在您的设备上。没有任何东西离开你的机器。
• 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检查员

uvx mcp dev src/whisper_telegram_mcp/server.py

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feat/amazing-feature)
3. 运行测试(pytest tests/ -v -m "not integration")
4. 用常规承诺进行承诺(feat:, fix:, docs:等等）
5. 打开拉取请求

许可证

麻省理工学院