fast-mcp-telegram

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

デモを試す

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 メソッドを直接実行、エンティティの解決、PII／認証情報フィールドはデフォルトで除外（生データを取得するには include_sensitive=true）— 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.leshchenko1979/fast-mcp-telegram