whisper-telegram-mcp

Транскрибируйте и говорите — двусторонняя голосовая связь для Claude через Telegram

MCP-сервер, который дает Claude возможности двусторонней голосовой связи через Telegram: транскрибируйте входящие голосовые сообщения с помощью Whisper и отвечайте синтезированной речью. Работает с Claude Desktop, Claude Code и любым клиентом, совместимым с MCP.

Что он делает

• Транскрибирует локальные аудиофайлы -- OGG, WAV, MP3, FLAC и другие

• Транскрибирует голосовые сообщения Telegram -- передайте file_id, получите текст обратно

• Озвучивает текст в виде голосовых заметок -- синтезируйте речь и отправляйте обратно в формате OGG (воспроизводится как голосовая заметка в Telegram)

• Два бэкенда транскрипции -- локальный faster-whisper (бесплатно, конфиденциально) или OpenAI Whisper API (облако)

• Автоматический режим -- сначала пробует локальный, при сбое переключается на OpenAI

• Определение языка -- автоматически или укажите код ISO-639-1

• Временные метки на уровне слов -- опциональная детализированная синхронизация

Предварительные требования

Для Kokoro требуется Docker. Если Docker не запущен, голосовые ответы автоматически переключаются на OpenAI TTS или say в macOS.

Быстрый старт

Настройка за 30 секунд с помощью Claude Code

Самый быстрый способ начать — просто попросите 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

Настройка Telegram-бота

1. Откройте Telegram и напишите @BotFather

2. Отправьте /newbot и следуйте инструкциям для создания бота

3. Скопируйте токен (выглядит как 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        # 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, затем say в macOS. Настройте с помощью переменной окружения 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 (основные):

Голоса 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]"

# 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. Делайте коммиты с использованием conventional commits (feat:, fix:, docs: и т.д.)

5. Откройте pull request

Лицензия

MIT