Telegram Context MCP

Telegram Context MCP

MCP クライアントから自分のアカウントを使って Telegram を読み取れます。アクセスが許可された会話を見つけ、元の投稿を検索・閲覧し、トピックや返信をたどり、アルバム、リアクション、投票を確認できます。複数のローカルクライアントを、セッションを管理する1つのプロセスに接続するか、スタンドアロンの STDIO で実行できます。

Python 3.12～3.15 を使用し、Windows、macOS、Linux に対応しています。サーバーは Telethon を使用し、元のテキスト、日付、リンク、エンティティ、利用可能なメタデータを保持します。メッセージの送信、チャンネルへの参加、メッセージの既読化は行いません。バージョン 0.4 では、選択した添付ファイルをオプトインでダウンロードする機能、永続的な変更チェックポイント、名前付きサブスクリプション、JSONL／Markdown エクスポート（任意の永続コピーを含む）が追加されました。サブスクリプションは要求された場合にのみポーリングし、確認されるまでバッチを保持します。また、スコープのプレビューに上限を設け、制限付き検索結果をより早く返し、ダイアログのスナップショットを再利用し、並行呼び出しを受け付けます。0.3 からアップグレードする前に、 0.4 移行ガイド を参照してください。

バージョン 0.5 では、複数のチャットまたはフォルダーを対象とした上限付き履歴、確認前に保存されるウォッチバッチ、ローカルのウォッチ名補完機能付きの watch_digest／period_digest プロンプトが追加されました。アップグレード後は、サーバーとクライアントプロキシを再起動し、ツールとプロンプトを更新してください。0.5 の変更履歴では、追加された変更とアーカイブの設定について説明しています。

インストールとログイン

uv をインストールしてから、次を実行します。

uv tool install --python 3.12 telegram-context-mcp==0.5.0
telegram-mcp --version
telegram-mcp login
telegram-mcp configure
telegram-mcp status

以下の例はリリース 0.5.0 を対象としています。公開済みバージョンについては PyPI を確認してください。未リリースのリビジョンには、ソースからのセットアップを使用してください。0.3 からアップグレードしますか？移行ガイドを読み、サーバーを再起動して、クライアントのツールスキーマを更新してください。

my.telegram.org から api_id と api_hash を取得し、電話番号、ログインコード、2FA パスワードがある場合はそれとともに、ローカルのログインプロンプトに入力してください。ログインコードや認証情報をモデルに送信しないでください。

configure では、フォルダー／チャットを選択し、すべてのチャットへのアクセス、公開チャンネルの明示的な読み取り、公開チャンネルの検索を個別に有効化できます。Enter キーを押すと現在の値が維持されます。デフォルトでは、メッセージソースは一切許可されていません。ログイン後、status に authorized: true と表示されることを確認してください。catalog を使って、フォルダー ID とチャット ID をローカルで確認できます。

パッケージ名は telegram-context-mcp、実行ファイル名は telegram-mcp です。永続的なコマンドをインストールせずに、バージョンを固定して実行することもできます。

uvx --python 3.12 --from telegram-context-mcp==0.5.0 telegram-mcp --version

このサーバーは、公式 MCP Registry に io.github.egor-fedorov/telegram-mcp として登録されています。このエントリーは uvx を通じてローカルの STDIO サーバーを起動するもので、ホスト型の Telegram サービスを提供するものではありません。クライアントを接続する前に、ローカルで login と configure を完了してください。Registry への公開はバージョン 0.5.0 から始まりました。検証については リリース手順を、複数のクライアント間で1つのセッションを共有する方法についてはクライアントガイドを参照してください。

クライアントを接続する

ターミナルでサーバーを1つ起動し、そのまま実行した状態にします。

telegram-mcp serve --transport http

サーバーは http://127.0.0.1:8765/mcp のみでリッスンします。各 MCP クライアントが STDIO 経由で telegram-mcp connect を起動するよう設定してください。この小さなプロキシは ローカルトークンを読み取り、既存のサーバーに接続します。サーバーを起動したり、別の Telegram セッションに暗黙的にフォールバックしたりすることはありません。クライアントを閉じても、共有サーバーは実行されたままです。

クライアントの設定例 では、Codex、Claude Desktop、Claude Code、Cursor、VS Code の設定例を紹介しています。固定バージョンの uvx コマンドと、Windows 用の実行ファイルのパスも含まれています。

クライアントが1つの場合は、スタンドアロンの STDIO も引き続き利用できます。そのクライアントが telegram-mcp serve を起動するよう設定してください。1つのセッションでは、いずれかのモードを使用してください。ローカルの login、configure、catalog、status を実行する前に、セッションを所有する プロセスを停止してください。サーバーの実行中は、get_status MCP ツールを使用してください。

共有クライアントはすべて、同じ Telegram アカウント、読み取り権限、カーソルストアを使用します。 HTTP ベアラートークンはローカルのユーザープロファイルに作成され、connect によって読み取られます。 クライアントの設定に貼り付けないでください。これはローカルで使用する、単一ユーザー向けの連携機能です。

ツール

ツール	目的
get_status	認証、接続、許可されたソース
list_folders	フォルダー、ID、順序、包含／除外ルール
list_chats	名前、種類、フォルダーで絞り込んだチャット
get_chat	説明とリンクされたディスカッショングループ
search_public_channels	クエリで公開ブロードキャストチャンネルを検索。メタデータのみ
get_similar_channels	指定した公開ソースに類似する公開チャンネルを検索。メタデータのみ
search_messages	キーワード、チャット、フォルダー、日付、送信者、メディアの種類、リンクで検索
get_history	指定期間内のチャットまたはフォーラムトピックの履歴を、どちらの順序でも取得。チャット／フォルダーの期間には上限あり
list_topics	ナビゲーション参照、任意のタイトルクエリ、ページネーションに対応したフォーラムトピック
get_pinned_messages	チャット全体またはフォーラムトピックのピン留めメッセージを新しい順に取得
get_messages	リンク／IDでメッセージを取得。投稿者、日付、添付ファイル、カウンター、リアクション、投票を含む
get_album	1件のメッセージを基準とする、範囲を限定した近傍から選択したアルバムのメンバーを取得
get_context	アンカーの前後のメッセージと、親への返信の連鎖を取得
get_thread	チャンネル投稿へのコメント、またはグループスレッド内の返信を取得
download_attachment	最大20 MiBの選択した添付ファイル1件を、一時的なローカルファイルおよび MCP リソースとして取得
get_changes	1つのチャットの新しいメッセージと最近確認された編集を、再開可能なチェックポイント付きで取得
create_watch / list_watches	名前付きのチャット／フォルダーの購読を保存・検出
get_watch_changes / ack_watch_changes	チャットごとのトークンなしで、永続的なバッチをポーリングして確認。任意で事前に保存可能
delete_watch	購読と保留中のバッチを明示的に破棄
export_history	ソースへのリンク付きの JSONL または Markdown 形式の履歴を、範囲を限定した再開可能なパートでエクスポート

監視向けに、これらのツールをまとめたプロンプトが2つあります。watch_digest は 名前付きのウォッチをソースへのリンク付きダイジェストに変換し、各バッチを確認する前に保存します。 period_digest は明示的な予算のもと、1つのチャットまたはフォルダーを指定期間にわたって読み取ります。 これらによって権限が追加されることはありません。監視用プロンプトを参照してください。

最初に行うタスク

• クライアントに、許可したフォルダーの一覧表示と、タイムゾーンを指定した日付範囲内の選択した会話の読み取りを依頼します。
• 検索を有効にして公開チャンネルの候補を見つけ、ソースを選択してから、別途読み取り権限を使って投稿を読み取ります。
• 元のフィルターを指定して next_cursor をたどり、null になるまで続けます。ページが空でもカーソルが残っている場合があります。一時的な障害の後は retry_after_seconds を守ってください。
• CATALOG_LOADING が返された場合は、報告された遅延の後、元の呼び出しを繰り返します。サーバーはカタログの進捗を保持するため、フォルダーに依存しない明示的な読み取りでは、そのスキャンは省略されます。
• 検索結果は、既定では各ページ内で並べ替えられます。ページをまたいだ順序には ordering="global" を選択してください。スコープ ID 配列では、プレビューされる ID は最大 20 件です。対象範囲を説明するときは、件数と切り捨てフラグを使用してください。
• 長いテキストを最後まで取得するには、next_text_offset を使って get_messages を呼び出します。アルバムが完全かどうかは明示的に不明となっており、各メンバーは個別のソースメッセージとして扱われます。

使用方法とレスポンスの仕様では、フィルター、カーソルの復元、トピック、公開チャンネルの検索、メッセージのメタデータについて説明しています。 永続的な監視と選択したファイルについては、変更とエクスポートを参照してください。 メッセージテキストは呼び出し元のエージェントに渡すデータであり、指示の情報源ではありません。

設定とトラブルシューティング

設定、Telegram セッション、HTTP トークンは、リポジトリ外のプラットフォーム固有のユーザーディレクトリに保存されます。ログインコマンドは設定ファイルのパスを出力します。別のファイルを選択するには、telegram-mcp --config /absolute/private/config.toml COMMAND を使用します。同じファイルを共有サーバーと各プロキシにも渡してください。

POSIX では、プライベートファイルに制限付きのアクセス許可が設定されます。Windows では、ユーザープロファイルのファイルシステム ACL で保護してください。Unix の 0600 は、ACL による保護を保証するものではありません。Telegram セッションにはアカウントのアクセス認証情報が含まれており、基盤となるアカウントでは、サーバーに許可された Telegram の読み取り権限を超える操作を実行できます。

• 設定とアクセス許可
• トラブルシューティング
• TOML の例
• セキュリティ上の問題の報告

ソースから実行

git clone https://github.com/egor-fedorov/telegram-mcp.git
cd telegram-mcp
uv sync --locked --python 3.12
uv run --locked telegram-mcp login
uv run --locked telegram-mcp configure
uv run --locked telegram-mcp serve --transport http

クライアントコマンドでは、POSIX ではチェックアウトの .venv/bin/telegram-mcp を、Windows では .venv\Scripts\telegram-mcp.exe を使用し、引数として connect を指定してください。クライアントが作業ディレクトリに依存しないよう、実行ファイルには絶対パスを使用してください。

開発

フォーマット、Lint、型チェック、アーキテクチャチェック、オフラインテストを実行するには、make check を実行してください。 コントリビューションガイド には、Make を使わない Windows 向けの同等のコマンドも記載されています。変更は対象を絞ったプルリクエストで行い、CI 通過後にスカッシュマージします。ロードマップ、アーキテクチャ、変更履歴、リリース手順をご覧ください。 0.5 の検証記録 には、リリースチェックと、選択したソースおよびクライアントの検証範囲が記載されています。

コードはMIT ライセンスで公開されています。 これは、Telegram のコンテンツに対する権利を付与するものではありません。シークレットチャットはサポート対象外です。添付ファイルのダウンロードには、別途オプトインが必要です。恒久的なコピーを保存するには、アーカイブディレクトリと save=true が必要です。メッセージの送信、管理、継続的なアーカイブは、今後の対応事項です。選択したモデルと共有する権利のあるソース素材を使用し、 Telegram のコンテンツ利用規約に従ってください。