fast-mcp-telegram

Telegram MCP Server — Telegram 向けの Model Context Protocol（MCP）ゲートウェイです。コンテキスト効率に優れた 8 つのツールを備え、マルチテナントに対応し、MTProto ブリッジを提供します。

正式な GitHub リポジトリ：alexeyleshchenko/fast-mcp-telegram。このプロジェクトは以前、leshchenko1979/fast-mcp-telegram として公開されていました。古い GitHub URL は公開状態で 404 になります。インストール方法は引き続き pip install fast-mcp-telegram または uvx --from fast-mcp-telegram で、PyPI が安定した参照先です。

デモを試す

1. https://tg-mcp.l1979.ru/setup を開きます
2. Telegram モバイルアプリからQR コードをスキャンします（設定 → デバイス → QR コードをスキャン）。スマートフォンでの入力、OTP、2FA は不要です。または、代わりに電話番号を入力できます。
3. 成功ページから Bearer トークンをコピーします

続いて、使用方法を選択します。

MCP クライアント（AI アシスタント）

• セットアップページから mcp.json ファイルをダウンロードします
• サーバーを AI クライアントに追加し、「telegram で保存したメッセージに hello を送信して」と尋ねます

直接 API（curl）

• 以下のコマンドを実行します（TOKEN を自分のものに置き換えてください）。

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello!"}}'

仕組み

このサーバーは、AI エージェントと Telegram の API の間に位置します。

Your agent → MCP/HTTP → this server → MTProto → Telegram

できること： Telegram で認証し（QR、電話番号、またはボットトークン）、80 以上のマイクロ API の代わりに、AI に使いやすい 8 つのツールを公開します。また、上級ユーザー向けに生の MTProto をブリッジします。マルチテナント対応のため、1 つのサーバーで複数のユーザーを扱い、それぞれのセッションは分離されます。

機能

機能	説明
:building_construction: デュアルトランスポート	ローカルの MCP クライアントには Stdio、リモートデプロイには HTTP（本番環境では http-auth、開発環境ではオプションで http-no-auth）
:closed_lock_with_key: マルチユーザー認証	共有 http-auth サーバー：ユーザーごとに Bearer トークンを 1 つ、MCP 接続ごとに Telegram アカウントを 1 つ使用します。すぐに認証できる QR ログイン — 電話番号／OTP／2FA は不要です。
:dart: AI 向けに最適化	80 以上のマイクロツールを 8 つに統合 — コンテキスト効率に優れた設計、LLM に適した API、MCP ToolAnnotations
:globe_with_meridians: HTTP-MTProto ブリッジ	エンティティ解決と安全対策を備え、あらゆる Telegram API メソッドに curl から直接アクセスできます
:shield: セッション ACL	http-auth のプリンシパルごとの制限をオプトインで設定できます（ACL_ENABLED） — チャットレーン、read_only、blocked_peers、allow_mtproto、ACL_DENY_UNLISTED_PRINCIPALS。詳しくは SECURITY.md をご覧ください
:tv: QR とウェブでのセットアップ	Telegram モバイルで QR コードをスキャンしてすぐに認証（電話番号／OTP／2FA は不要）、または電話番号／コード／2FA による代替手段を利用できます — /setup で利用可能
:label: 1 つのエージェントで複数アカウントを利用	オプションの PREFIX_MCP_TOOLS_WITH_ACCOUNT — 1 つのエージェントが複数の MCP 接続（同じサーバー、異なるトークン）を使用する場合、ツール名にプレフィックスを付けて名前の衝突を防ぎます。標準的なマルチユーザーホスティングでは不要です
:rocket: MTProto プロキシのサポート	Fake TLS（EE プレフィックス）を自動適用し、標準プロキシを検出して MTProto プロキシ経由で接続します
:card_file_box: 統合セッション管理	セットアップとサーバーで共通の設定システムを使用します。共有マルチユーザーホストではトークンごとにセッションファイルを管理します
:cloud: S3 セッションストレージ	一時的なホスティング環境（Smithery、Fly.io、Railway）向けに、S3 互換のオブジェクトストレージにセッションを保存します
:mag_right: インテリジェント検索	グローバルおよびチャットごとのメッセージ検索に対応し、複数クエリの処理とインテリジェントな重複排除を備えています
:mag: 統合メッセージ API	検索、閲覧、ID による読み取り、返信を 1 つの get_messages ツールで実行 — 5 つのモードを 1 つに集約
:speech_balloon: あらゆるメッセージへの返信	1 つのパラメーターで、チャンネル投稿、フォーラムトピック、またはあらゆるメッセージへの返信を取得できます
:busts_in_silhouette: スマートな連絡先検索	統一されたエンティティスキーマ、フォーラムの検出、プロフィール情報の拡充に対応し、ユーザー、グループ、チャンネルを検索します
:file_folder: フォルダーによる絞り込み	ダイアログフォルダー（アーカイブ済み、カスタムフォルダー）でチャットを絞り込みます。整数 ID または名前で指定できます
:envelope: 高度なメッセージ機能	送信、編集、返信、フォーラムトピックへの投稿、書式設定、ファイル添付、電話番号を使ったメッセージ送信に対応します
:paperclip: 安全なファイル処理	SSRF 対策、サイズ制限、アルバム対応、オプションの HTTP 添付ファイルストリーミングを備えたリッチメディア共有
:outbox_tray: インラインファイルアップロード	files パラメーターで Data: URI（base64）によるファイルアップロードが可能です — すべてのトランスポートモードで動作し、ファイル名を保持し、画像は写真として送信します
:microphone: 音声文字起こし	Premium アカウント向けに、並列処理とポーリングを用いた音声からテキストへの自動変換を行います
:zap: 高いパフォーマンス	非同期処理、並列クエリ、メモリ効率に配慮したバッチ処理
:shield: 本番環境での高い信頼性	自動再接続、設定可能なログ記録、包括的なエラー処理

クイックスタート

1. インストールして認証する

最短の方法（リモートサーバー）： /setup を開く → QR コードをスキャンする → トークンをコピーする（デモを試すを参照）。

CLI の方法（ローカル stdio）： fast-mcp-telegram-setup を一度実行して Telegram セッションを作成します。その後、fast-mcp-telegram がセッションを提供します。

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --phone-number="+123456789"

ボットトークンを使う方法（電話番号、OTP 不要）： --phone-number の代わりに BOT_API_TOKEN を設定します。インストールガイドを参照してください。

2. MCP クライアントを設定する

stdio モード（ローカル）： MCP クライアントの設定（例：claude_desktop_config.json）に追加します。stdio（標準入力／出力）は、ローカル MCP クライアントのデフォルトのトランスポートです。

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["fast-mcp-telegram"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash"
      }
    }
  }
}

http-auth モード（リモート）： MCP クライアントの設定（例：claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "telegram": {
      "url": "https://tg-mcp.l1979.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

セットアップページの QR コードをスキャンしてトークンを取得するか、独自のサーバーをデプロイする方法についてはインストールガイドを参照してください。

3. 利用を開始する

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello!"}}

リモートサーバーにデプロイする

VDS に独自の MCP サーバーをデプロイできます。手順についてはインストールガイドを参照してください。

利用可能なツール

ツール	用途	主な機能
search_messages_globally	すべてのチャットを横断して検索	複数語句での検索、日付による絞り込み、チャットの種類による絞り込み
get_messages	メッセージの統合取得	検索／閲覧、ID による読み取り、返信の取得（投稿／トピック／メッセージ）、すべてのモードでの日付による絞り込み
send_message	新しいメッセージを送信	ファイル添付（URL／ローカルファイル／データ URI）、従来の書式設定（markdown/html）、parse_mode=rich のリッチメッセージ、フォーラムのトピックへの返信
edit_message	既存のメッセージを編集	従来の書式設定または parse_mode=rich による書式設定
find_chats	ユーザー／グループ／チャンネルを検索	複数語句での検索、連絡先の検索、フォルダーによる絞り込み、ユーザー名／電話番号の検索
get_chat_info	詳細なプロフィール情報を取得	メンバー数、自己紹介／概要、オンライン状態、フォーラムのトピック、共通のグループ、拡張データ
send_message_to_phone	電話番号にメッセージを送信	連絡先の自動管理、任意のクリーンアップ、ファイル対応（URL／データ URI）、parse_mode=rich
invoke_mtproto	Telegram API を直接呼び出す（上級ユーザー向け）	生の MTProto メソッド、エンティティの解決、安全対策。MTProto ブリッジを参照

詳細なドキュメントと使用例については、ツールリファレンスを参照してください。

ドキュメント

• インストールガイド - ローカル環境のセットアップとリモートサーバーへのデプロイ
• ツールリファレンス - ツールの完全なドキュメント
• MTProto ブリッジ - curl を使用した API への直接アクセス
• コントリビューション - コントリビューター向けガイドライン
• セキュリティ - セキュリティ機能とベストプラクティス

テレメトリー

v0.30.1 以降、匿名のツールテレメトリーを送信します。6 時間ごとにハートビートを送信し、認証情報やメッセージの内容は収集しません。DO_NOT_TRACK=1 を設定するとオプトアウトできます。ADR 0005を参照してください。

v0.38.0 以降、認証フローのテレメトリーを送信します。セットアップ中（電話番号、QR、ボットトークン、再認証）にアトミックイベントを記録します。フロー完了時にバッファーをフラッシュします。ADR 0008を参照してください。

ライセンス

MIT ライセンス。LICENSEを参照してください。

mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram