chigwell/telegram-mcp

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

Telegram MCP Server – 概要

Telegram MCP は、AI エージェント（Claude、Cursor、または Model Context Protocol（MCP）を話す任意のクライアント）が Telegram アカウントをネイティブツールのセットであるかのように操作できるようにする、自己ホスト型の Python サーバーです。MCP ツール呼び出しを Telethon ベースの Telegram API アクションに変換し、Telegram でできるすべてのこと（チャットの読み取り、メッセージの送信、グループの管理、連絡先、メディア、フォルダー、イベント、さらには音声からテキストへの文字起こし）を公開します。

コアアイデア

MCP ↔ Telegram ブリッジ – サーバーはオープンソースの Model Context Protocol を実装し、Telegram 操作を LLM 駆動エージェントが呼び出せる構造化された JSON ベースのツールに変換します。
エージェントフレンドリー – 結果はサニタイズされた JSON で、サーバーは特別なエラーオブジェクト（例：telegram_premium_required）を報告するため、エージェントは動作を適応できます。

これでできること

領域	機能例
アカウント	複数の設定済みアカウントを一覧表示し、ラベルで呼び出しをルーティングします。
チャットとグループ	チャットの一覧表示、グループの作成/参加/退出、管理者、禁止、スローモード、トピック、招待リンク、既読レシートなどの管理。
メッセージ	送信、編集、削除、転送、スケジュール、ピン留め、リアクション、投票作成、返信、検索、コンテキスト取得、リッチな書式（テーブル、数式、折りたたみセクションを含む Markdown/HTML）を使用 – プレミアム限定。
連絡先	一覧表示、検索、追加、ブロック、インポート/エクスポート、エイリアスの記憶（例：エイリアスを教えた後、`send_message("андрей бекендер", …)` が機能します）。
メディア	ファイル、ステッカー、GIF、音声メモのアップロード/ダウンロード、および 4 つのエンジンのいずれかを使用した音声/ビデオの文字起こし（Groq Whisper、Telegram Premium、OpenAI 互換、またはローカル Faster-Whisper）。
プロフィールとプライバシー	プロフィール情報、写真、プライバシー設定、ボットコマンドの取得/設定。
フォルダーと下書き	フォルダーの一覧表示、作成、並べ替え、削除; 下書きの保存、一覧表示、クリア; バックアップ/復元用のフォルダー定義のスナップショット。
イベント	新しいメッセージを待機（`wait_for_new_message`）、またはファイルを監視できるエージェント（例：Claude Code）向けに JSON 行をファイルに書き込むコールバックスタイルの受信フィードを有効化。
カスタム絵文字とタップ可能な日付	カスタム絵文字 ID を取得し、`<tg-emoji>` タグで再利用; `format_date` でタップ可能な日付チップを埋め込み。

音声文字起こしの詳細

Groq – ホスト型 Whisper-large-v3-turbo、GROQ_API_KEY が必要。デフォルトでアップロードは 25 MiB に制限。
Telegram – Telegram Premium のネイティブ文字起こしを使用（無料、Telegram 上に留まる）が、最後のセグメントが失われる可能性があります。
OpenAI – 任意の /audio/transcriptions エンドポイント（OpenAI、Parakeet、LocalAI など）。
Whisper – ローカル Faster-Whisper モデル（pip install 'telegram-mcp[whisper]'）。

文字起こしは SQLite ファイルにキャッシュされ、繰り返しのリクエストはキャッシュにヒットし、同時の同一リクエストは結合されます。

クイックスタート

クローンしてインストール – git clone https://github.com/chigwell/telegram-mcp.git && uv sync（Python 3.10+ が必要）。
セッション文字列を作成 – uv run session_string_generator.py（QR コードまたは電話番号フロー）。
設定 – .env.example を .env にコピーし、TELEGRAM_API_ID、TELEGRAM_API_HASH、TELEGRAM_SESSION_STRING を入力。
実行 – uv run telegram-mcp（または Docker – 下記参照）。
オプション – 長時間実行サーバー用に永続的な SQLite セッションに移行（uv run telegram-mcp-migrate-session）。

デプロイオプション

Docker – 公式イメージは自動的にビルド; data/transcripts（文字起こしキャッシュ）と状態ディレクトリ（~/.local/state/telegram-mcp）用にボリュームをマウント。
複数アカウント – .env で複数のアカウントを定義（例：ACCOUNT_1_LABEL、ACCOUNT_2_LABEL）、account 引数で呼び出しをルーティング。
プロキシサポート – TELEGRAM_PROXY を SOCKS/HTTP プロキシ URL に設定。
セキュリティ – エイリアス、セッションデータ、受信フィードログを保存するファイルは、所有者のみの権限（600/700）で作成されます。README は、同名の PyPI パッケージ telegram-mcp をインストールしないよう警告しています（無関係です）。

誰が使うべきか？

LLM 搭載のパーソナルアシスタント – Telegram メッセージを読み取ったり操作したりする必要がある（例：Claude Code、Cursor、カスタム MCP ホスト）。
自動化エンジニア – 複数の Telegram アカウントで動作するボットを構築し、ロジックをハードコードされたスクリプトではなく LLM に保持する。
研究者 – 明示的なエラーオブジェクトとプライバシー重視の設計（許可リストのチャットアクセス、エイリアス確認など）により、LLM が実際のメッセージングプラットフォームと安全に対話する方法を探求する。

ライセンスとコミュニティ

ライセンス： Apache 2.0 – 商用および研究用途に寛容。
ステータス： 積極的にメンテナンス（GitHub Actions で lint、Docker ビルド、CI）。プルリクエストによる貢献を歓迎します。

TL;DR

Telegram MCP Server は、Telegram を豊富な MCP 互換ツールセットに変換する Python ブリッジであり、LLM エージェントが Telegram コンテンツをプログラム的に読み取り、書き込み、管理、文字起こしできるようにします。複数アカウント、リッチな書式、カスタム絵文字、安全でキャッシュ対応の音声文字起こしをサポートしています。