TG multi-account MCP

TG マルチアカウント MCP

ロシア語ドキュメント

セルフホスト可能な Model Context Protocol サーバーです。AI エージェントは、明示的に選択したユーザーアカウントと任意のボットを通じて Telegram を利用できます。アカウントはローカルのウェブウィザードで QR コードをスキャンし、必要に応じて Telegram の 2FA パスワードを入力して接続します。

このサーバーは Telegram クライアントではなく、エージェント向けのツールとして設計されています。チャット履歴の検索、フォルダーやスレッドの読み取り、添付ファイルのダウンロード、更新の追跡、下書きの作成、メッセージの送信ができます。すべての操作で使用するアカウントまたはボットを指定する必要があり、サーバーが送信者を暗黙的に選択することはありません。

重要

Telegram セッションからは、対応するアカウントにアクセスできます。このサービスは管理下にあるインフラストラクチャで実行し、状態ディレクトリと MCP トークンを保護してください。また、エージェントトークンには必要な権限のみを付与してください。

これは非公式の連携機能であり、Telegram API を使用しています。Telegram との提携や、Telegram による推奨を受けているものではありません。

対応機能

• 複数の Telegram ユーザーアカウントに対応。それぞれに独自の QR／2FA 登録フローとセッションがあります。
• アカウントの無効化、再接続、アカウントとローカルセッションの完全削除を行うダッシュボードコントロール。
• BotFather トークンを使って個別に接続する、任意の Telegram ボット。
• Bearer トークン認証を備えた Streamable HTTP MCP。
• チャット、フォルダー、メッセージ、添付ファイル、メンション、トピック、返信スレッド、全体検索用のツール。
• チャット検索時のキリル文字／ラテン文字の翻字マッチング。
• ユーザーとボットによる送信、編集、予約送信、転送、リアクション、下書き、冪等性キー。
• read、send、admin 権限に加え、ID／チャットの許可リストで範囲を限定したエージェントトークン。
• メッセージ本文、クエリ、パスワード、トークンを記録せず、メタデータのみを記録するプライベートな運用ダッシュボード。
• 設定可能な埋め込みプロバイダーを使った、継続的なローカル意味検索インデックスとプロジェクトメモリー。
• テキスト RAG と S3 添付ファイルのルールを分離し、グループ／チャンネルのデフォルト設定とチャットごとの上書きに対応。
• キューの速度、滞留数、完了予定時刻（ETA）の監視に加え、検索、フィルター、ページネーションに対応したチャットテーブル。
• Caddy が HTTPS を管理する Docker Compose デプロイ。

MCP ツールと動作に関する注意事項は、ツールカタログをご覧ください。プロジェクトメモリーとローカルアーカイブの説明もあります。

ダッシュボードのプレビュー

以下は、架空のアカウント、チャット、識別子、統計情報を使った、稼働中のダッシュボードのブラウザーキャプチャです。実際の Telegram メッセージやデプロイ時の秘密情報は含まれていません。数値はインターフェースの例であり、測定された性能ではありません。

デフォルトのストレージルールは、チャットごとの上書き設定とは別に管理されます。

モバイル表示 · モバイル用ルールエディター

要件

• Python 3.12+
• uv
• my.telegram.org から取得した Telegram の api_id と api_hash

Docker とドメインが必要なのは、Compose でデプロイする場合のみです。

クイックスタート

公開済みパッケージをインストールします。

uv tool install tg-account-mcp
tg-mcp setup
TG_MCP_PORT=8765 tg-mcp serve

ソースをチェックアウトして開発する場合：

uv sync --frozen
uv run tg-mcp setup
TG_MCP_PORT=8765 uv run tg-mcp serve

setup はローカルのターミナル入力を通じて Telegram API の認証情報を求め、ランダムな MCP アクセストークンを生成します。電話番号やアカウントのパスワードは求めません。

http://127.0.0.1:8765/ を開き、アカウント設定ウィザードに従います。

1. Telegram → Settings → Devices → Link Desktop Device で QR コードをスキャンします。
2. 2FA が有効な場合は、Telegram クラウドパスワードを入力します。
3. アカウントのローカル表示名を設定します。

ウィザードを再度実行すると、アカウントを追加できます。ボットは任意で、ダッシュボードから別途追加します。保存前に Telegram でトークンを検証します。

状態ディレクトリのデフォルトは ~/.local/share/tg-mcp です。--state-dir または TG_MCP_STATE_DIR で変更できます。

MCP クライアントを接続する

メインのトークンをローカルで表示します。

uv run tg-mcp show-token

クライアントで Streamable HTTP エンドポイントと Bearer ヘッダーを使用するよう設定します。

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer <MCP_TOKEN>"
  }
}

設定の周辺構造は MCP クライアントによって異なります。OAuth が必須で、Bearer ヘッダーを設定できないクライアントには、現在対応していません。

まず get_capabilities、list_accounts、list_bots を使用してください。アカウントとボットに関するすべての操作では、acct_… や bot_… などの安定した ID を明示する必要があります。

「ITQ で今日の、自分のタスクに関するメッセージを見せて」のようなフォルダーを基準としたリクエストでは、以下の同意要件に従ってこのコンテンツを処理する許可がある場合、エージェントは list_folders を呼び出し、その後、date_from と date_to に一致する値、および Europe/Madrid などの IANA タイムゾーンを指定して get_folder_messages を呼び出せます。

Codex プラグイン

このリポジトリには、認証付きの自動サービス検出機能と、チャットの解決、フォルダーの要約、完全なページネーション、添付ファイル、下書き、冪等な送信に対応するワークフロースキルを備えた Codex プラグインも含まれています。

codex plugin marketplace add Mesteriis/tg-account-mcp --ref main
codex plugin add tg-account-mcp@tg-account-mcp

このプラグインは、ローカルマシンとネットワークに対して、認証付きの検出リクエストを送信します。検出リクエストと応答は、設定済みの MCP トークンを使って認証されます。検出されたエンドポイントが認証される前に、トークン自体がブロードキャストまたは送信されることはありません。検出をスキップして特定の HTTPS エンドポイントを使用するには、TG_MCP_URL を設定します。サーバーのセットアップとプロンプトの例については、Codex プラグインガイドを参照してください。

Codex とサービスが同じマシン上で同じ OS ユーザーとして実行されている場合、ブリッジは保護されたローカル状態からトークンを自動的に読み取ります。別のマシン上のサービスを使う場合は、Codex プロセスに TG_MCP_TOKEN を設定してください。

責任ある利用と Telegram の規約

運用者は Telegram API 利用規約 および コンテンツライセンス規約 を遵守する必要があります。特に、次の点に注意してください。

• 自身の Telegram api_id を取得して使用してください。
• ユーザーの知識と同意なしに、そのユーザーに代わって操作を行わないでください。
• 関連するすべてのユーザーが、対象となるコンテンツと状況に対して、明示的かつ十分な情報に基づく肯定的な継続的同意を行っていない限り、Telegram のコンテンツを AI／ML システムに提供するために、スクレイピング、インデックス化、収集、集約、学習、ベンチマークへの利用、またはその他の方法で提供しないでください。
• メッセージやファイルにアクセスされる人々の権利、プライバシー、指示を尊重してください。

このソフトウェアをインストールしても、Telegram のコンテンツを利用する権利が付与されるわけではありません。合成データ、自分が保存したメッセージ、または必要な同意を得ており、その同意が有効なチャットを使用してください。

エージェントのアクセス制御

setup で生成されるトークンは管理者トークンです。create_agent_token を使ってエージェントごとに個別のトークンを発行し、次の条件で制限します。

• スコープ：read、send、または admin。
• 許可するアカウント ID とボット ID。
• 許可するチャット ID。

エージェントトークンは SHA-256 ハッシュのみが保持され、平文のトークンは一度だけ返されます。アクセスを取り消すには revoke_agent_token を使います。チャットを制限したトークンでは、近隣のチャットの情報が漏れる可能性があるため、受信トレイの集約、フォルダー、またはグローバル検索のツールを使用できません。

LAN への直接デプロイ

Compose の HTTPS プロキシを使用せず、信頼できるプライベートネットワークでサービスを LAN にバインドして起動するには、次のようにします。

TG_MCP_BIND=0.0.0.0 \
TG_MCP_PORT=8765 \
TG_MCP_TRUSTED_NETWORKS=192.168.1.0/24 \
tg-mcp serve

TG_MCP_TRUSTED_NETWORKS は任意で、デフォルトは空です。プライベート CIDR 範囲を設定すると、直接接続している TCP ピアのアドレスがその範囲のいずれかに含まれるクライアントは、Bearer トークンなしで /mcp を使用できます。これにより、その範囲内のすべてのデバイスに MCP の完全な管理者アクセス権が付与されます。信頼できる LAN の外部にサービスを公開しないでください。このチェックでは、転送されたクライアントアドレスのヘッダーは使用されません。

サーバーの LAN アドレスをブラウザーで開きます。ダッシュボードではトークンが要求されないため、アクセスできるすべてのユーザーがメタデータを表示し、Telegram ID を管理できます。同一オリジンからのブラウザーリクエストは自動的に許可されます。別のフロントエンドオリジンを使用する場合は、TG_MCP_ALLOWED_ORIGINS に追加する必要があります。TCP 8765 とディスカバリー用 UDP 38475 は、信頼できるネットワークからのみ許可してください。信頼できないネットワークを経由する場合は、VPN または認証機能付きリバースプロキシを使用してください。

Docker Compose によるデプロイ

サーバーのドメインを設定し、受信 TCP 80/443 を許可してから、次のコマンドを実行します。

cp .env.example .env
# Set TG_MCP_DOMAIN to the real hostname in .env.
docker compose build
docker compose run --rm --no-deps tg-mcp setup
docker compose up -d

初期設定を行うには、https://your-domain.example/ を開きます。ダッシュボードは意図的にトークンなしで利用できるようになっています。ネットワークポリシーまたは認証機能付きリバースプロキシでドメインを保護してください。エージェントは引き続き、Bearer トークンを使用して https://your-domain.example/mcp に接続します。

Compose は、認証付き UDP ディスカバリーもポート 38475 で公開し、同じプライベートネットワーク上のクライアントにその HTTPS エンドポイントを通知します。必要に応じて両側の TG_MCP_DISCOVERY_PORT を変更するか、ローカルディスカバリーをデプロイに含めない場合は TG_MCP_DISCOVERY=false を設定します。

Caddy が HTTPS を終端し、アプリケーションのポートはパブリックに公開されません。アプリケーションコンテナは、読み取り専用のルートファイルシステムを使用し、非特権ユーザーとして実行されます。状態ボリュームごとに、アプリケーションのレプリカを 1 つだけ実行してください。

セキュリティモデル

• 状態ディレクトリには 0700 のモードが必要です。機密ファイルには 0600 を使用します。
• シンボリックリンク、ハードリンクされた機密ファイル、所有者が異なるファイル、過度に広いアクセス権限は拒否されます。
• Web UI では、サードパーティのスクリプト、フォント、分析機能、リモートアセットを使用しません。
• ダッシュボードのアカウントデータとセットアップ API は、サーバーにアクセスできるクライアントがトークンなしで利用できます。MCP エンドポイントでは、オペレーターが TG_MCP_TRUSTED_NETWORKS を明示的に設定しない限り、Bearer トークンが必要です。この設定を有効にすると、該当するプライベート CIDR 内のクライアントに MCP の完全なアクセス権が付与されます。
• Host と Origin の値は、完全一致する許可リストに照合されます。ワイルドカードは拒否されます。
• ログと操作履歴には、メッセージ本文、検索語句、認証情報、QR URL、2FA パスワードは記録されません。
• テストでは偽の Telegram アダプターを使用し、実際のメッセージは送信しません。

バックアップを作成する際は、サービスを停止してから状態ボリュームをバックアップし、バックアップを暗号化して保管してください。セッションが漏えいした場合は、Telegram → デバイスから失効させてください。脆弱性の報告については SECURITY.md を、運用の詳細とエラーコードについてはロシア語の README を参照してください。

ローカルチャットアーカイブ

選択したチャットを有効にすると、ローカルに履歴、編集バージョン、全文検索を永続的に保存できます。削除済みコンテンツの保持はデフォルトで無効です。アーカイブの設定と制限事項およびツールカタログを参照してください。

プロジェクトメモリとセマンティック検索では、ソースに基づく下書き、明示的な承認、オプトイン方式のローカル Ollama 埋め込みを利用できます。プロジェクトは分離されており、ソースの編集や削除が行われると、派生したメモリは無効になります。埋め込みモデルがなくてもキーワード検索を利用できます。 オプションのバックグラウンド RAG は、現在および将来のすべてのユーザーアカウントのチャット、グループ、チャンネルを自動的に検出し、ローカルの埋め込みを維持します。

既知の制限事項

• Telegram のクラウド API ではシークレットチャットを利用できません。
• メッセージの削除と分散／複数レプリカでのデプロイはサポートされていません。
• 履歴ツールは必要に応じて Telegram を読み取ります。ローカルアーカイブにコピーされるのは明示的に選択されたチャットのみです。確認された範囲や削除イベントが完全である保証はありません。
• ページ間に新しいメッセージが届くと、位置ベースのページネーションで項目が重複したり、スキップされたりすることがあります。
• poll_updates は直近の 2,000 件のイベントをプロセスメモリに保持し、再起動後にリセットされます。

開発

uv sync --frozen
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
node --test tests/ui-table-state.test.cjs
uv build
TG_MCP_DOMAIN=mcp.example.test docker compose config --quiet
docker build -t tg-account-mcp:local .

アーキテクチャとコントリビューター向けのセットアップについては、docs/architecture.md と CONTRIBUTING.md を参照してください。リリースとレジストリの手順については、 docs/PUBLISHING.md を参照してください。

ライセンス

Apache License 2.0 の下でライセンスされています。

ローカル優先のメッセージ取得

優先して使用するメッセージ取得ツールとして、find_messages(account_id, query, chat_id=..., telegram="auto") を使用してください。ローカルの字句一致とセマンティック候補を組み合わせ、アカウント／チャット／メッセージ ID で重複を除去し、ローカルの結果やカバレッジが不十分な場合は、上限付きの Telegram ページを 1 つ読み取ります。telegram="never" の場合、Telegram は読み取りません。"always" の場合は最新状態を検証します。省略可能な date_from／date_to は、両端を含む UTC の日付です。include_context=true を指定すると、ローカルのみのモードが選択されていない限り、上位の結果 1 件とその前後 2 件ずつのメッセージのみを読み取ります。

partial、warnings、local_coverage、semantic_partial、および取得元情報を確認してください。セマンティック検索の対象は、スコープ内のインデックス済み直近 2000 件に制限されます。字句検索は保持されているアーカイブ全体を対象とします。アカウント全体のインベントリは完全性が保証されていないため、アカウント全体に対する自動クエリでは Telegram も参照することがあります。結果は上限付きの順位付けであり、完全なエクスポートではありません。また、スコアは信頼度を示すものではありません。Telegram のカーソルを使った検索を続けるには、返されたネイティブの cursor_tool（search_messages または search_all_messages）を使い、アカウント／クエリ／チャット／日付の引数を維持してください。

フォールバックとコンテキストの読み取りは、アカウントの適応型読み込みゲートを共有します。Telegram のエラー、クールダウン、またはタイムアウトが発生した場合も、明示的な警告とともにローカルの結果は保持されます。削除されたコンテンツは返されず、取得リクエストによってソースが自動的に有効化、アーカイブ、または再インデックスされることもありません。チャット制限付きトークンでは、許可された chat_id を指定する必要があります。アカウント全体の取得は、読み取りが行われる前に拒否されます。

継続的なテキストと S3 の取り込み

プライベートチャットでは、常にテキスト RAG とサポートされているすべての添付ファイル形式が有効になります。グループとチャンネルのデフォルトでは、テキスト RAG は有効、S3 は無効です。デフォルトは「設定」→「RAG と S3」で、チャットごとのルールは RAG ページで設定するか、管理者として set_ingestion_policy を使用してください。検出済みのチャットでは、その種類のルールを上書きするか、再び継承するように設定できます。get_ingestion_policy は、1 つのチャットに適用される実効ルールを読み取ります。 グローバル設定の変更には、ID やチャットによる制限のない管理者トークンが必要です。明示的に一時停止されたアーカイブ、対象外のチャット、無効なアカウントは一時停止されたままです。

RAG のテキストと S3 ファイルは個別に切り替えられます。S3 の種類は photo、video、document、audio、voice、video_note、sticker、animation です。キャプションはテキスト RAG に取り込めます。ファイルは OCR や文字起こしを行わず、元のバイナリーオブジェクトとして保存されます。 ルールを無効にすると以降の取り込みは停止しますが、既存のデータは保持されます。テキスト RAG を再度有効にすると履歴の対象範囲が再開され、S3 を有効にすると保存済みの添付ファイルのメタデータが取り込まれます。 新しいライブメッセージはすぐにキューに追加され、転送は非同期で新しいものから順に行われます。準備が整ったアカウントには公平に順番が割り当てられます。Telegram の検出は、設定された間隔ごとに引き続き実行されます。ダウンロードは、履歴の読み取りと同じ永続的な適応型 Telegram ゲートを共有します。FloodWait による一時停止と間隔の延長は、どちらにも適用されます。セマンティック埋め込みは引き続きローカルで処理されます。

プライベートな S3 互換エンドポイントを、TG_MCP_S3_ENDPOINT、TG_MCP_S3_REGION（デフォルトは garage）、TG_MCP_S3_BUCKET、TG_MCP_S3_PREFIX（デフォルトは telegram）、TG_MCP_S3_ACCESS_KEY、TG_MCP_S3_SECRET_KEY で設定してください。エンドポイント、バケット、両方の認証情報を、プライベートな環境設定ファイルでまとめて指定してください。S3 を利用するには、バックグラウンド RAG とローカルの埋め込みプロバイダーが必要です。エンドポイントはループバックまたはプライベートネットワークである必要があります。パブリックエンドポイントや環境変数で設定されたプロキシは使用されません。バケットと権限を限定した認証情報は別途用意し、決してコミットしないでください。

ワーカーはプライベートな再開可能スプール、永続的なアップロード要求、冪等なオブジェクトキーを保持し、アップロード後にオブジェクトの長さと SHA-256 メタデータを確認します。また、ローカルの空き容量を 5 GiB 確保します。ダウンロード前に消失した Telegram ファイルは、スキップとして報告されます。ダッシュボードのステータスには、ファイル名や認証情報を表示せずに、キュー内、保存済み、失敗、S3 削除待ちの件数が表示されます。アーカイブを消去するとオブジェクトの削除が予約されます。media_cleanup_pending は、この非同期クリーンアップキューを報告します。 Telegram の削除保持には、チャットに既存の retain_deleted 設定が適用されます。SQLite アーカイブ、スプール、認証情報、S3 サービスのデータはまとめてバックアップしてください。同じマシン上の S3 サービスはストレージであり、独立したバックアップではありません。

ダッシュボードのテーブルとルール

RAG ページでは、キューの監視と検索可能なチャット一覧を組み合わせています。アカウント、チャットの種類、状態、継承ルール／カスタムルール、または S3 ポリシーで絞り込み、結果を並べ替えて、1 ページあたり 10／25／50／100 行を選択できます。除外されたチャットも表示されます。チャット名を開くと、そのルールをインラインで編集できます。ステータスのポーリング後も、下書きと選択中のページは保持されます。 プライベートチャットのルールは固定されています。デフォルトのグループ／チャンネルルールは「設定」→「RAG と S3」にあり、サーバー／モデル情報は「サービスについて」で読み取り専用です。

アクティビティテーブルでは、直近 30 日間に保持された最新 100 件の操作を対象に、絞り込み、並べ替え、ページネーションができます。フッターにはこの対象範囲が表示されます。履歴のカバー率は、Telegram 全体に対する推定割合ではなく、既知の状態に基づきます。チャットごとの S3 件数には、アップロード済みオブジェクトの重複を除いた数と、保留中／エラーのジョブ数が表示されます。ファイル名やオブジェクトキーは表示されません。

キューストリップには、埋め込み処理の速度、テキストの正味流入速度、保存済みテキストのバックログ、およびキューの正味排出速度に基づく完了予測時間が表示されます。グラフは保存済みテキストのキューを追跡します。推定には、まだダウンロードされていない Telegram の履歴は含まれません。キューが増加しているか、排出が停止している場合、パネルには完了時刻の代わりにその状態が表示されます。診断を展開すると、アカウントの処理間隔と履歴のカバー率も確認できます。添付ファイルのエラーは再試行状態とともに別途報告されます。テキストのキューがすべて処理済みでも、すべてのファイルがアップロードされたとは限りません。Telegram の履歴読み込みと添付ファイルのダウンロードでは、ローカルの埋め込み処理速度とは独立して、共有の適応型間隔が維持されます。

ステータス API が利用できなくなった場合、パネルには最後に表示されたデータが保持され、古いデータであることが示されます。ルールの保存に失敗した場合は、再試行できるように下書きが保持されます。未保存の編集がある間は、保存またはキャンセルするまで、フィルターやページを変更できません。ルールをオフにしても、既存のデータは保持されます。