tdl-mcp

tdl-mcp

tdl CLI を利用した、Claude やその他の MCP ホスト向けの 読み取り専用 Telegram アクセスです。

自分の Telegram アカウントから、チャットの一覧表示、最近のメッセージの閲覧、メディアのダウンロードができます。シンプルな 5 つのツールを使います。メッセージを送信したり、何かを変更したり、ログイン情報に触れたりすることはありません。

🇰🇷 韓国語のドキュメントはこちら → README.ko.md

tdl-mcp を選ぶ理由

ほとんどの Telegram MCP サーバーは MTProto ライブラリ（Telethon、gramjs など）を組み込み、my.telegram.org で独自の Telegram アプリを作成して api_id／api_hash を取得するよう求めます。また、その多くはユーザーに代わってメッセージを送信できます。

tdl-mcp は異なる、あえてシンプルな方法を採用しています。

• 設計上、読み取り専用です。 サーバーでできるのは、チャットの一覧表示、メッセージのエクスポート、ファイルのダウンロードだけです。それ以外は何もできません。メッセージを送信、編集、削除したり、ログインしたりするコードパスはありません。
• api_id／api_hash の設定は不要です。 ログインは tdl login -T qr を使って、ターミナル上で一度だけユーザー自身が行います。スマートフォンで QR コードをスキャンすれば完了です。Telegram アプリの登録も不要です。
• 実績のあるダウンローダーを基盤にしています。 tdl（⭐ 7.5k 以上）が、並列高速ダウンロード、再開、--skip-same による重複排除などの処理を担います。
• 小規模で監査しやすい設計です。 通常の JavaScript ファイル 1 つ、依存関係 2 つ（@modelcontextprotocol/sdk、zod）で、ビルド手順もありません。サーバー全体を 5 分で読むことができます。

Claude / MCP host  ←stdio→  tdl-mcp (Node)  →subprocess→  tdl CLI  →MTProto→  Telegram

クイックスタート

1. tdl をインストールする

# macOS
brew install telegram-downloader

# Linux / WSL
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash

# Windows (PowerShell)
iwr -useb https://docs.iyear.me/tdl/install.ps1 | iex

.tdl-version に固定されているバージョン以上であれば、どのバージョンでも動作するはずです。CI ではその固定バージョンに対するテストを継続的に実施しています（互換性と最新状態の維持を参照）。

2. Telegram にログインする（一度だけ）

tdl login -T qr

Telegram モバイルアプリで QR コードをスキャンしてください （設定 → デバイス → デスクトップデバイスをリンク）。セッションはお使いのマシンの ~/.tdl に保存され、すべての MCP ホストで共有されます。ログインは一度だけです。tdl-mcp 自体がログインやログイン情報の更新を行うことはありません。

3. MCP ホストにサーバーを追加する

Node.js ≥ 22 が必要です。

Claude Code:

claude mcp add --scope user telegram -- npx -y tdl-mcp

Claude Desktop／その他の MCP ホスト（汎用 mcpServers JSON）:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tdl-mcp"]
    }
  }
}

4. 試してみる

アシスタントに、次のようなことを尋ねてみてください。

「Telegram のチャットを一覧表示して。クオンツ取引についてのチャットを探して。」

「@some_channel の直近 20 件のメッセージを表示して。」

「そのチャンネルでメッセージ 1500 以降に投稿された PDF をすべて ~/Papers にダウンロードして。」

ツールから未ログインだと報告された場合は、ターミナルで tdl login -T qr を実行してから再試行してください。手動で必要な手順はこれだけです。

ツール

ツール	引数	機能
tg_status	—	tdl セッションがログイン済みかどうかを確認します。エラーは返しません。{logged_in:true, chats:N} または {logged_in:false, hint} を返します。
tg_chats	filter?	ダイアログを [{id, type, name, username}] として一覧表示します。filter は名前／ユーザー名／IDに対する大文字と小文字を区別しない部分一致検索です。
tg_messages	chat、last_n?（デフォルトは50、最大500）、since_id?、with_text?（デフォルトはtrue）	チャットから最近のメディアメッセージを、コンパクトな {id, date, file, text} オブジェクトとしてエクスポートします（返される件数は最大200件で、切り捨てられた場合はその旨が記されます）。since_id を指定すると、既知のIDより後のメッセージのみを取得でき、増分読み込みに便利です。
tg_download	chat、since_id?、last_n?（デフォルトは100）、extensions?（CSV形式、例："xlsx,pdf"）、dest?（デフォルトは ~/Downloads/telegram）	--skip-same を指定してチャットからメディアをダウンロードします。新たにダウンロードしたファイルの絶対パス、または「一致するファイルはありません」という分かりやすいメッセージを返します。
tg_download_url	urls（https://t.me/... リンクの配列）、extensions?、dest?	リンクで指定した特定のメッセージのメディアをダウンロードします。すべてのURLが https://t.me/ で始まることを検証します。

chat には、tg_chats に表示されたとおりの数値IDまたは @username／ドメインを指定できます。

環境変数

変数	効果
TDL_BIN	tdl バイナリへのパスです。デフォルトは PATH 上の tdl で、見つからない場合は /opt/homebrew/bin/tdl を使用します（GUIから起動されたMCPホストでは、Homebrewの PATH が引き継がれないことがよくあります）。
TDL_NS	tdl の名前空間です。すべての呼び出しで -n <ns> として渡されます。Telegramのアカウント／セッションを分ける場合に使用します。

ホストのサーバー設定で次のように設定します。

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "tdl-mcp"],
      "env": { "TDL_NS": "work" }
    }
  }
}

互換性と最新状態の維持

tdl-mcp は tdl CLI をシェル経由で実行するため、実際の依存対象は tdl のコマンドラインインターフェースです。このインターフェースは自動的に検証されます。

• .tdl-version には、このパッケージのテスト対象となる tdl リリースが固定されています。
• scripts/contract.mjs は、ログインせずに、サーバーが使用するすべてのフラグ（chat ls -o json、chat export -c/-T/-i/-o/--with-content、dl -f/-u/-i/-d/--skip-same、グローバルな -n）が、その tdl バイナリに引き続き存在することを検証します。CIでは、すべてのプッシュとPRで実行されます。
• スケジュールされたワークフローが tdlのリリースを監視します。新しいバージョンが公開されると、新しいバイナリを使ってコントラクトテストを実行し、リリースノートから破壊的変更を示すマーカーを検索します。通常の更新はシンプルなバージョン更新PRとなり、懸念のある変更は、ラッパーコードを適応させるAI支援のアップグレードPRにエスカレーションされます。

したがって、固定されたバージョンより新しい tdl を使っていても、問題なく動作する可能性は非常に高いです。万が一動作しない場合でも、このリポジトリが事前に検出します。

開発

git clone https://github.com/rixile9999/tdl-mcp.git
cd tdl-mcp
npm install
npm test          # smoke (MCP protocol, login-free) + contract (tdl CLI surface)

• npm run smoke はstdio経由でサーバーを起動し、ツールカタログ、tg_status の形式、入力検証を確認します。ログイン済みかどうかにかかわらず成功します。
• npm run contract は、インストール済みの tdl バイナリがサーバーの使用するCLIインターフェースに対応しているか確認します。別のバージョンでテストする場合は、scripts/install-tdl.sh [vX.Y.Z] を実行して、指定した（チェックサム検証済みの）tdlリリースをインストールできます。

PRを歓迎します。サーバーは読み取り専用のままにしてください。送信、編集、削除を行うツールは、このプロジェクトの対象外です。

セキュリティに関する注意事項

• ~/.tdl 内のtdlセッションはユーザーアカウントの全権限を持つ認証情報です。これを読み取れる人は、あなたのTelegramアカウントを操作できます。SSHキーと同様に保護し、リポジトリ、共有バックアップ、他のマシンにコピーしないでください。
• tdl-mcp はセッション自体を読み取ったり送信したりすることはありません。ローカルで tdl バイナリを実行するだけです。tdl自身のTelegram通信を除き、マシンの外にデータが送信されることはありません。
• ダウンロード先は指定したディレクトリ（dest）です。デフォルトは ~/Downloads/telegram です。

Telegram の利用規約に関する注意

tdl はボットではなく、通常のユーザーセッション（MTProto）を操作します。自分のアカウントを静かに、読み取り専用で個人利用する自動化は一般に許容されていますが、過度なクロールを行うとアカウントが制限される可能性があります。範囲（last_n、since_id）を控えめにし、大量の並列取得を避け、再ダウンロードを防ぐために --skip-same を活用してください。

ライセンス

このリポジトリ内のすべてのものに適用されるライセンスはMITです。

tdl 自体は独立したプロジェクトであり、AGPL-3.0 の下でライセンスされています。tdl-mcp は tdl を同梱、リンク、変更していません。インストール済みのバイナリを別プロセスとして呼び出すため、AGPL が適用されるのは tdl であり、このラッパーではありません。tdl は公式の配布経路を通じて、ご自身でインストールしてください（上記のステップ 1）。