Secure Telegram

アカウント全体を渡すことなく、Claude、Cursor、または任意の MCP クライアントを Telegram に接続できます。

このデモは合成データを使用して実行されます。実際の Telegram 接続も、使用可能な認証情報もありません。

❌ 一般的な Telegram MCP の設定

• AI クライアントがアカウント全体のセッションを保持します。すべてのチャット、すべての連絡先、すべての書き込みが対象です。
• アクセスはすべて許可するか、すべて拒否するかです。仕事用エージェントが家族のグループを読めてしまいます。
• セッション認証情報が設定ファイルや .env にプレーンテキストで保存されます。

✅ secure-telegram-mcp を使う場合

• 各 AI クライアントにエンドポイントを割り当てます。それぞれが独自の API キーを持ち、選択したチャットとフォルダーにアクセスが限定されます。
• 読み取り／書き込みの操作は呼び出しごとに再確認され、確認に失敗した場合はアクセスを拒否します。ツールメニューは機能の確認用であり、権限を定めるものではありません。
• Telegram セッションは保存時に暗号化されます（AES-256-GCM、scrypt でラップされたキー）。デフォルトではマシンに紐付けられ、または PIN で保護されます。

例：

すべての MCP 接続は 1 つのエンドポイントキーで認証され、そのエンドポイントのアカウントにスコープが限定された Telegram アダプターを受け取ります。キーがないクライアントにできるのは、ツールの一覧表示だけです。エンドポイントごとに異なるログイン済みアカウントを使用できます。同じアカウント上のエンドポイントは、1 つの Telegram バックグラウンド接続を共有します。スコープ外のチャットには一切アクセスできません。

機能

• 🔑 エンドポイントごとの API キー — 各 AI クライアントに独自のキーとスコープを割り当て、ログイン済みアカウントの 1 つ（または複数）に固定します。保存されるのはソルト付きキーのハッシュのみです。
• 📁 フォルダー単位のアクセス制限 — エンドポイントを Telegram のフォルダー、チャット、またはチャンネルに紐付けます。書き込みアクセスはエンドポイントごとに明示的に有効化します。
• 🔒 保存時にセッションを暗号化 — セッションとポリシーに AES-256-GCM のエンベロープを使用します。PIN、リカバリーキーファイル、マシン紐付けのロック解除スロットを利用できます。
• 🚦 BAN 対策の送信間隔制御 — メッセージ、転送、検索にアカウントごとのトークンバケットを適用します。また、飽和の兆候が現れた時点でアカウント全体をバックオフさせるサーキットブレーカーも備えています。送信間隔の制御によってフラッド制限のリスクは下がりますが、BAN を確実に防げるものではありません。
• 👤 人間が確認する書き込み — エンドポイントごとの確認を任意で設定できます。MCP のエリシテーションに対応するクライアントが必要です。対応していないクライアントでは、書き込み確認が必須のエンドポイントは安全側に動作し、確認なしの書き込みは行わず、すべてブロックします。
• ⛔ 生の MTProto インターフェースなし — invoke による回避手段も、モデルから変更可能なスコープもありません。この設計を維持するための CI アーキテクチャガードを備えています。

クイックスタート

前提条件： Node.js ≥ 20.10、および my.telegram.org/apps から取得した Telegram の api_id／api_hash。

1. セットアップを実行する

npx -y secure-telegram-mcp setup

セットアップでは、次の項目を順番に設定します。

1. Telegram アプリの認証情報 — 前提条件のリンクから取得した api_id / api_hash。
2. ログイン方法 — QR コード（すでにログインしているスマートフォンでスキャン）または電話番号 + コード。アカウントで2段階認証を有効にしている場合は、そのパスワードも求められます。
3. セッション名 — Enter キーを押すと、候補（Telegram のユーザー名、またはユーザー名がない場合は main）を使用します。
4. PIN の設定、または PIN なし — デフォルトは PIN なしです（このマシンに紐づく暗号化が適用され、ロック解除は不要です）。PIN を設定した場合は、再起動のたびに再入力します。忘れた PIN は復元できません。
5. エンドポイント — 名前を付けてから、ピッカーでチャット／フォルダーを選びます。r または Space で読み取り、w で書き込み、s で保存、? でキー操作の一覧を表示します。

終了時に、エンドポイントの API キーが貼り付け可能なクライアント設定内に一度だけ表示されます。ターミナルを閉じる前にコピーしてください。問題が発生した場合は、トラブルシューティングをご覧ください。

2. エンドポイントを1つの MCP クライアントに追加する

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "secure-telegram-mcp", "connect"],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "tgmcp_..."
      }
    }
  }
}

トークンだけでエンドポイントが選択され、認証されます。クライアント設定に api_id、api_hash、PIN の情報を含める必要はありません。セットアップではエンドポイントごとに1つのブロックが出力されます。それぞれのブロックは個別のクライアントにのみ追加してください。1つのクライアントに複数のエントリーをまとめると、意図的にそのスコープの和集合が付与されます。

claude mcp add telegram --env TELEGRAM_MCP_ENDPOINT_TOKEN=tgmcp_... -- npx -y secure-telegram-mcp connect

3. ロックを解除する（PIN を設定した場合のみ）

デフォルトのマシン紐づけ保護を使用している場合は、この手順を省略してください。クライアントの接続時にサービスが自動的に起動します。PIN を設定した場合：

npx -y secure-telegram-mcp start

PIN は対話形式で入力します。クライアントに PIN を渡す必要はありません。複数クライアントの例、無人でのロック解除、環境変数、ポリシーの手動編集については、使用方法と運用をご覧ください。

ツール

18 個のツールがあり、実行時に確認される 8 つの権限動詞によって制御されます。

転送には送信元と送信先の両方の権限が必要です。送信元チャットへの read と、送信先への forward が必要です。ローカルメディアの送信は、意図的に 2 段階のフローになっています。prepare_media は、制限されたメディアルート内のファイルに対する、不透明で有効期限付きのハンドルを返し、send_media がそのハンドルを使用します。ツールの全一覧と動詞の意味については、使用方法と操作を参照してください。

セキュリティモデル

• 暗号化された Telegram セッションと封印済みポリシーは、単一のローカルサービスが管理します。MCP shim が別の Telegram セッションを開くことはありません。
• すべての呼び出しで、エンドポイントトークンを現在の封印済みポリシーと再照合するため、キーをローテーションすると既存の接続が無効になります。
• 生の MTProto ツールはなく、モデルが自らの権限範囲を広げる方法もありません。
• 書き込みは、ACL → 必要に応じた人間による確認 → クォータ → 監査の順に処理され、各ゲートで安全側に失敗します。
• Telegram の文章はモデルに渡す前に Unicode サニタイズされます（制御文字と書式文字を除去し、長さを制限します）。書き込み、拒否、メディアの外部送信は、追記専用の NDJSON 監査ログに記録されます。
• 既知の制限： 強制適用の境界はローカル OS ユーザーです。プロセス自体が侵害された場合、エンドポイント ACL では基盤となる全アカウントセッションの機能を制限できません。また、サニタイズでは意味上のプロンプトインジェクションを無効化できません。

読み取り専用のエンドポイントから send_message を実行しようとすると、ACL ゲートで停止され、メッセージ本文を含まない NDJSON の 1 行が監査ログに記録されます。

{"v":1,"timestampIso":"2026-07-17T09:41:22.310Z","endpointName":"work","verb":"send","outcome":"deny","targetChatId":"-1001234567890","reason":"VERB_NOT_GRANTED"}

クライアントに表示されるのは ACL_DENIED エラーだけです。権限範囲外の相手に対しても同様に拒否され、PEER_OUT_OF_SCOPE が返されます。

大切な Telegram アカウントに接続する前に、非目標と残存リスクを含む脅威モデルをすべてお読みください。コンポーネントの境界については、アーキテクチャを参照してください。

ドキュメント

• 使用方法と操作 — クライアント、エンドポイント、コマンド、環境変数、Docker、メディア、ツール一覧。
• セキュリティ — 脅威モデル、保証、残存リスク、強化されたデプロイ。
• アーキテクチャ — プロセスの所有権、信頼境界、ポリシーのライフサイクル。
• 設定例 — スキーマに準拠していますが、意図的に使用できないプレースホルダーを含みます。

開発

npm run ci     # typecheck + lint + architecture guard + knip + tests
npm run build

アーキテクチャガードは、禁止された MCP サーフェスと未レビューの MTProto リクエストコンストラクターを拒否します。ESLint は依存関係の境界を適用し、GramJS をインフラストラクチャ層内に制限します。PR を作成する前に、CONTRIBUTING.mdをお読みください。

ライセンス

MIT

非公式プロジェクトです。Telegram FZ-LLC との提携、同社による承認、または同社からの後援を受けていません。 「Telegram」は Telegram FZ-LLC の商標です。このソフトウェアは Telegram API に接続します。 各ユーザーが自身の API 認証情報を用意する必要があります。