Whisper Telegram MCP

🎙️ whisper-telegram-mcp

文字起こしと音声合成 — Telegram経由でClaudeに双方向の音声機能を

Telegram経由でClaudeに双方向の音声機能を提供する MCP サーバーです。受信したボイスメッセージをWhisperで文字起こしし、合成音声で返信します。Claude Desktop、Claude Code、その他MCP互換クライアントで動作します。

✨ 主な機能

• ローカル音声ファイルの文字起こし — OGG、WAV、MP3、FLACなどに対応
• Telegramボイスメッセージの文字起こし — file_id を渡すだけでテキストを返却
• テキストをボイスノートとして読み上げ — 音声を合成し、OGGとして返信（Telegramでボイスノートとして再生）
• 2つの文字起こしバックエンド — ローカルの faster-whisper（無料・プライベート）または OpenAI Whisper API（クラウド）
• 自動モード — まずローカルを試し、失敗時はOpenAIにフォールバック
• 言語検出 — 自動検出、またはISO-639-1コードを指定可能
• 単語レベルのタイムスタンプ — オプションで詳細なタイミングを取得

📋 前提条件

⚠️ 重要なお知らせ

KokoroにはDockerが必要です。 Dockerが起動していない場合、音声返信は自動的にOpenAI TTSまたはmacOS sayにフォールバックします。

🚀 クイックスタート

Claude Codeで30秒セットアップ

最も手軽な方法 — 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を再起動し、次のように伝えます：「音声文字起こし用にTelegramボットをセットアップして」 — 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. MCP設定のenvに TELEGRAM_BOT_TOKEN を追加（下記参照）
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        # 音声ファイルへの絶対パス
language: str | None  # ISO-639-1コード（例: "en"）、None = 自動検出
word_timestamps: bool # 単語レベルのタイムスタンプを含める（デフォルト: false）

transcribe_telegram_voice

file_id: str          # Telegramボイスメッセージのfile_id
bot_token: str | None # ボットトークン（TELEGRAM_BOT_TOKEN環境変数にフォールバック）
language: str | None  # ISO-639-1コード、None = 自動検出
word_timestamps: bool # 単語レベルのタイムスタンプを含める（デフォルト: false）

speak_text

テキストをOGG/Opus音声ファイルに変換します。利用可能な最良のTTSバックエンドを自動選択します。

text: str             # 合成するテキスト
voice: str            # ボイス名（デフォルト: "af_sky"）
output_path: str|None # 出力.oggファイルの任意のパス

TTSバックエンド（優先順位順）

auto モード（デフォルト）では、サーバーはまずKokoro、次にOpenAI、最後にmacOS say を試します。TTS_BACKEND 環境変数で設定できます。

Kokoroをローカルで起動

Kokoro FastAPIはPyPIにはありません — MCPサーバーを実行する前に起動してください：

# Docker（最も簡単、推奨）
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# Apple Silicon（GPU高速化）
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu-mac:latest

# ソースから
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のデータ保持ポリシーに従って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]"

# ユニットテストを実行
pytest tests/ -v -m "not integration"

# 統合テストを実行（初回実行時に約150MBのモデルをダウンロード）
pytest tests/ -m integration -v

# カバレッジ付きで実行
pytest tests/ --cov=src/whisper_telegram_mcp --cov-report=term-missing

MCP Inspector

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. プルリクエストを作成

📄 ライセンス

MIT