使用说明

密语电报mcp

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

一主控程序通过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代码
字级时间戳 --可选的细粒度计时

先决条件

功能	要求
转录（本地）	无-通过捆绑更快的耳语 `[local]` 额外费用
转录（云）	`OPENAI_API_KEY` 有人是。
语音回复-Kokoro（最佳质量）	码头工人 --奔跑 `docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest`
语音回复——OpenAI TTS（回退）	`OPENAI_API_KEY` 有人是。
语音回复-macOS说（最后手段）	仅限Mac，无需设置

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

快速开始

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

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

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

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

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

一个命令 `uvx`

uvx whisper-telegram-mcp

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

或使用pip安装

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

电报机器人设置

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

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`	将本地音频文件（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        # 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后端（按优先级顺序）：

后端	成本	质量	设置
心（本地）	免费	自然，高品质	手动启动（见下文）
OpenAI TTS （云）	~0.015美元/1k字符	高品质	`OPENAI_API_KEY` 有人是。
macOS说（回退）	免费	机器人	仅限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 有人是。

科科罗声音（主要）：

声音	口音	风格
`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

	本地（快速私语）	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)对于英语来说稍微准确一些。

隐私和数据

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

贡献

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

许可证

麻省理工学院

使用说明

密语电报mcp

它的作用

先决条件

快速开始

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

一个命令 uvx

或使用pip安装

电报机器人设置

整合

克劳德桌面

克劳德代码

工具

transcribe_audio

transcribe_telegram_voice

speak_text

转录应答格式

配置

运作原理

本地vs OpenAI

型号尺寸

隐私和数据

发展

MCP检查员

贡献

许可证

相关 MCP

多模态生成API服务

Hugging Face MCP服务器

语音处理服务

macOS通知服务

短视频生成工具

文本转语音服务

一个命令 `uvx`

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`