whisper-telegram-mcp

Transkribieren und sprechen — Zwei-Wege-Sprachkommunikation für Claude via Telegram

Ein MCP-Server, der Claude Zwei-Wege-Sprachfunktionen via Telegram verleiht: Transkribieren eingehender Sprachnachrichten mit Whisper und Antworten mit synthetisierter Sprache. Funktioniert mit Claude Desktop, Claude Code und jedem MCP-kompatiblen Client.

Was er kann

• Lokale Audiodateien transkribieren -- OGG, WAV, MP3, FLAC und mehr

• Telegram-Sprachnachrichten transkribieren -- übergeben Sie eine file_id, erhalten Sie Text zurück

• Text als Sprachnachricht ausgeben -- Sprache synthetisieren und als OGG zurücksenden (wird in Telegram als Sprachnachricht abgespielt)

• Zwei Transkriptions-Backends -- lokales faster-whisper (kostenlos, privat) oder OpenAI Whisper API (Cloud)

• Auto-Modus -- versucht zuerst lokal, greift bei Fehlern auf OpenAI zurück

• Spracherkennung -- automatisch oder durch Angabe eines ISO-639-1-Codes

• Zeitstempel auf Wortebene -- optionales, fein abgestimmtes Timing

Voraussetzungen

Kokoro erfordert Docker. Wenn Docker nicht läuft, greifen Sprachantworten automatisch auf OpenAI TTS oder macOS say zurück.

Schnellstart

Einrichtung in 30 Sekunden mit Claude Code

Der schnellste Weg zum Start — sagen Sie Claude Code einfach, dass es die Einrichtung für Sie übernehmen soll:

1. Fügen Sie dies zu Ihrer .mcp.json (Claude Code) oder claude_desktop_config.json (Claude Desktop) hinzu:

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

2. Starten Sie Claude neu und sagen Sie: "Set up my Telegram bot for voice transcription" — Claude führt Sie durch die Erstellung des Bots mit BotFather und die Konfiguration.

Ein Befehl mit uvx

uvx whisper-telegram-mcp

Keine Installation erforderlich -- uvx erledigt alles.

Oder Installation mit pip

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

Telegram-Bot-Einrichtung

1. Öffnen Sie Telegram und schreiben Sie @BotFather

2. Senden Sie /newbot und folgen Sie den Anweisungen, um einen Bot zu erstellen

3. Kopieren Sie das Token (sieht aus wie 1234567890:ABCdef...)

4. Fügen Sie TELEGRAM_BOT_TOKEN zu Ihrer MCP-Konfigurationsumgebung hinzu (siehe unten)

5. Schreiben Sie Ihrem Bot, um zu starten — er antwortet nur autorisierten Benutzern

Das Claude Telegram-Plugin übernimmt die Zugriffskontrolle. Siehe dessen Dokumentation für die Einrichtung von Pairing/Allowlist.

Integration

Claude Desktop

Fügen Sie dies zu Ihrer Claude Desktop-Konfiguration hinzu (~/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

Fügen Sie dies zu Ihrer .mcp.json im Projekt hinzu:

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

Tools

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

Konvertiert Text in eine OGG/Opus-Audiodatei. Wählt automatisch das beste verfügbare TTS-Backend aus.

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

TTS-Backends (in Prioritätsreihenfolge):

Im auto-Modus (Standard) versucht der Server zuerst Kokoro, dann OpenAI, dann macOS say. Konfigurieren Sie dies mit der Umgebungsvariable TTS_BACKEND.

Kokoro lokal starten:

Kokoro FastAPI ist nicht auf PyPI — starten Sie es, bevor Sie den MCP-Server ausführen:

# 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

Sobald es läuft, erkennt der MCP-Server es automatisch unter http://127.0.0.1:8880/v1. Überschreiben Sie dies mit der Umgebungsvariable KOKORO_BASE_URL.

Kokoro-Stimmen (primär):

OpenAI-Stimmen (Fallback):

Kokoro-Stimmennamen werden beim Fallback automatisch auf das nächste OpenAI- oder macOS-Äquivalent gemappt.

Rückgabe:

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

Senden Sie den zurückgegebenen file_path als Telegram-Anhang, und er erscheint als native Sprachnachricht.

Transkriptions-Antwortformat

Alle Transkriptionstools geben Folgendes zurück:

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

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Funktionsweise

                         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 sendet einen Tool-Aufruf via MCP (stdio-Transport)

2. Bei Telegram-Sprachnachrichten wird die Datei über die Bot-API heruntergeladen

3. auto_transcribe() wählt das beste verfügbare Transkriptions-Backend

4. auto_tts() wählt das beste verfügbare TTS-Backend (Kokoro -> OpenAI -> macOS)

5. Ergebnisse werden als strukturiertes JSON zurückgegeben

Lokal vs. OpenAI

Modellgrößen

Englisch-only Varianten (tiny.en, base.en, small.en, medium.en) sind für Englisch etwas genauer.

Privatsphäre & Daten

• Lokales Backend (faster-whisper): Audio bleibt auf Ihrem Gerät. Nichts verlässt Ihren Rechner.

• OpenAI-Backend: Audio wird gemäß der Datenaufbewahrungsrichtlinie an die OpenAI-API gesendet

• Temporäre Dateien: Von Telegram heruntergeladenes Audio wird nach /tmp geschrieben und sofort nach der Transkription gelöscht

• Logs: Gehen nur an stderr — keine Audioinhalte oder Anmeldedaten werden jemals protokolliert

Entwicklung

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

Mitwirken

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feat/amazing-feature)

3. Führen Sie Tests aus (pytest tests/ -v -m "not integration")

4. Committen Sie mit konventionellen Commits (feat:, fix:, docs: etc.)

5. Öffnen Sie einen Pull Request

Lizenz

MIT