whisper-telegram-mcp

Transcribe y habla — voz bidireccional para Claude a través de Telegram

Un servidor MCP que dota a Claude de capacidades de voz bidireccional a través de Telegram: transcribe mensajes de voz entrantes con Whisper y responde con voz sintetizada. Funciona con Claude Desktop, Claude Code y cualquier cliente compatible con MCP.

Qué hace

• Transcribe archivos de audio locales -- OGG, WAV, MP3, FLAC y más

• Transcribe mensajes de voz de Telegram -- pasa un file_id y obtén el texto de vuelta

• Habla texto como notas de voz -- sintetiza voz y envíala de vuelta como OGG (se reproduce como una nota de voz en Telegram)

• Dos motores de transcripción -- faster-whisper local (gratuito, privado) o API de Whisper de OpenAI (nube)

• Modo automático -- intenta primero localmente, y recurre a OpenAI si falla

• Detección de idioma -- automática o especificando un código ISO-639-1

• Marcas de tiempo a nivel de palabra -- temporización precisa opcional

Requisitos previos

Kokoro requiere Docker. Si Docker no está ejecutándose, las respuestas de voz recurren automáticamente a OpenAI TTS o a say de macOS.

Inicio rápido

Configuración en 30 segundos con Claude Code

La forma más rápida de empezar: solo dile a Claude Code que lo configure por ti:

1. Añádelo a tu .mcp.json (Claude Code) o 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. Reinicia Claude y di: "Set up my Telegram bot for voice transcription" — Claude te guiará a través de la creación del bot con BotFather y la configuración de todo.

Un comando con uvx

uvx whisper-telegram-mcp

No requiere instalación -- uvx se encarga de todo.

O instálalo con pip

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

Configuración del bot de Telegram

1. Abre Telegram y envía un mensaje a @BotFather

2. Envía /newbot y sigue las instrucciones para crear un bot

3. Copia el token (se ve como 1234567890:ABCdef...)

4. Añade TELEGRAM_BOT_TOKEN a la configuración de entorno de tu MCP (ver abajo)

5. Envía un mensaje a tu bot para empezar — solo responderá a usuarios aprobados

El plugin de Telegram para Claude gestiona el control de acceso. Consulta su documentación para la configuración de emparejamiento/lista de permitidos.

Integración

Claude Desktop

Añádelo a tu configuración de 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

Añádelo al .mcp.json de tu proyecto:

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

Herramientas

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

Convierte texto a un archivo de audio OGG/Opus. Selecciona automáticamente el mejor motor TTS disponible.

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

Motores TTS (en orden de prioridad):

En modo auto (predeterminado), el servidor intenta primero Kokoro, luego OpenAI y finalmente say de macOS. Configúralo con la variable de entorno TTS_BACKEND.

Iniciando Kokoro localmente:

Kokoro FastAPI no está en PyPI — inícialo antes de ejecutar el servidor 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

Una vez en ejecución, el servidor MCP lo detecta automáticamente en http://127.0.0.1:8880/v1. Sobrescríbelo con la variable de entorno KOKORO_BASE_URL.

Voces de Kokoro (primarias):

Voces de OpenAI (alternativas):

Los nombres de las voces de Kokoro se asignan automáticamente al equivalente más cercano de OpenAI o macOS cuando se recurre a ellos.

Retorno:

{
  "file_path": "/tmp/tmpXXX.ogg",
  "size_bytes": 16555,
  "backend": "kokoro",
  "voice": "af_sky",
  "success": true,
  "error": null
}

Envía la file_path devuelta como un archivo adjunto de Telegram y aparecerá como una nota de voz nativa.

Formato de respuesta de transcripción

Todas las herramientas de transcripción devuelven:

{
  "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
}

Configuración

Toda la configuración se realiza mediante variables de entorno:

Cómo funciona

                         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 envía una llamada de herramienta a través de MCP (transporte stdio)

2. Para mensajes de voz de Telegram, el archivo se descarga a través de la API del Bot

3. auto_transcribe() elige el mejor motor de transcripción disponible

4. auto_tts() elige el mejor motor TTS disponible (Kokoro -> OpenAI -> macOS)

5. Los resultados se devuelven como JSON estructurado

Local vs OpenAI

Tamaños de modelo

Las variantes solo en inglés (tiny.en, base.en, small.en, medium.en) son ligeramente más precisas para el inglés.

Privacidad y datos

• Motor local (faster-whisper): El audio permanece en tu dispositivo. Nada sale de tu máquina.

• Motor OpenAI: El audio se envía a la API de OpenAI según su política de retención de datos

• Archivos temporales: El audio descargado de Telegram se escribe en /tmp y se elimina inmediatamente después de la transcripción

• Registros: Van solo a stderr — nunca se registra contenido de audio ni credenciales

Desarrollo

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

Inspector MCP

uvx mcp dev src/whisper_telegram_mcp/server.py

Contribución

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad (git checkout -b feat/amazing-feature)

3. Ejecuta las pruebas (pytest tests/ -v -m "not integration")

4. Confirma con commits convencionales (feat:, fix:, docs:, etc.)

5. Abre una solicitud de extracción (pull request)

Licencia

MIT