whisper-telegram-mcp

文字起こしと発話 — Telegram経由でClaudeに双方向の音声機能を提供

MCPサーバーであり、Telegramを通じてClaudeに双方向の音声機能を提供します。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コードを指定
単語レベルのタイムスタンプ -- オプションで詳細なタイミング情報を取得可能

前提条件

機能	要件
文字起こし（ローカル）	なし — `[local]` エクストラ経由でfaster-whisperをバンドル
文字起こし（クラウド）	`OPENAI_API_KEY` 環境変数
音声返信 — Kokoro（最高品質）	Docker — `docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest` を実行
音声返信 — OpenAI TTS（フォールバック）	`OPENAI_API_KEY` 環境変数
音声返信 — macOS say（最終手段）	Macのみ、設定不要

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

クイックスタート

Claude Codeで30秒でセットアップ

最も簡単な開始方法です。Claude Codeにセットアップを依頼してください：

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

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ボットのセットアップ

Telegramを開き、@BotFather にメッセージを送ります
/newbot を送信し、指示に従ってボットを作成します
トークン（1234567890:ABCdef... のような形式）をコピーします
MCP設定の環境変数に TELEGRAM_BOT_TOKEN を追加します（下記参照）
ボットにメッセージを送って開始します。承認されたユーザーのみに応答します

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`	ローカルの音声ファイル（OGG、WAV、MP3など）をテキストに文字起こし
`transcribe_telegram_voice`	`file_id` を指定してTelegramのボイスメッセージをダウンロードし文字起こし
`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バックエンド（優先順位順）:

バックエンド	コスト	品質	セットアップ
Kokoro (ローカル)	無料	自然、高品質	手動で開始（下記参照）
OpenAI TTS (クラウド)	~$0.015/1k文字	高品質	`OPENAI_API_KEY` 環境変数
macOS say (フォールバック)	無料	ロボット的	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 環境変数で上書き可能です。

Kokoroの音声（プライマリ）:

音声	アクセント	スタイル
`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

	ローカル (faster-whisper)	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）は、英語に対してわずかに精度が高くなります。

プライバシーとデータ

ローカルバックエンド (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]"

# 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

貢献

リポジトリをフォーク
フィーチャーブランチを作成 (git checkout -b feat/amazing-feature)
テストを実行 (pytest tests/ -v -m "not integration")
コミットメッセージの規約に従ってコミット (feat:, fix:, docs: など)
プルリクエストを作成

ライセンス

MIT

whisper-telegram-mcp

whisper-telegram-mcp

機能

前提条件

クイックスタート

Claude Codeで30秒でセットアップ

`uvx` でのワンコマンド実行

またはpipでインストール

Telegramボットのセットアップ

統合

Claude Desktop

Claude Code

ツール

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`

文字起こしのレスポンス形式

設定

仕組み

ローカル vs OpenAI

モデルサイズ

プライバシーとデータ

開発

MCP Inspector

貢献

ライセンス

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

whisper-telegram-mcp

機能

前提条件

クイックスタート

Claude Codeで30秒でセットアップ

uvx でのワンコマンド実行

またはpipでインストール

Telegramボットのセットアップ

統合

Claude Desktop

Claude Code

ツール

transcribe_audio

transcribe_telegram_voice

speak_text

文字起こしのレスポンス形式

設定

仕組み

ローカル vs OpenAI

モデルサイズ

プライバシーとデータ

開発

MCP Inspector

貢献

ライセンス

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`uvx` でのワンコマンド実行

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`