Telegram Archive Mcp

telegram-archive-mcp

あらゆるTelegram-Archiveインスタンスに対応する MCP サーバーです。LLM はこれを使ってメッセージを検索したり、チャットを閲覧したり、アーカイブされた Telegram の履歴を読んだりできます。

機能

• stdio と Streamable HTTP で、MCP 2026-07-28 と、それ以前の 2024-11-05 までのすべてのリビジョンに対応しています。引き続き initialize ハンドシェイクを使用するクライアントも、そのまま利用できます。
• 1つのチャットまたはすべてのチャットを一度に検索したり、チャットをページごとに読んだり、タイムゾーンに合わせたカレンダー上の1日分を読んだり、1つのメッセージの前後の会話を読んだりできます。
• フォーラムトピック、ピン留めされたメッセージ、フォルダー、チャットごとの統計情報に対応しています。
• メッセージに添付された写真を、モデルが確認できる画像として返します。画像が大きい場合は1568ピクセルに縮小されます（get_media）。
• refresh_stats を除くすべてのツールは読み取り専用です。READ_ONLY=1 を設定すると、このツールも非表示になります。
• TELEGRAM_ARCHIVE_USER と TELEGRAM_ARCHIVE_PASS を使い、/api/login 経由で Telegram-Archive にサインインします。
• HTTP はデフォルトでループバックアドレスをリッスンし、Origin を検査してリクエスト本文のサイズを制限します。ほかのアドレスでは MCP_AUTH_TOKEN が必要です。
• npm パッケージ、Docker イメージ、マルチアーキテクチャ対応の Go バイナリとして提供されます。

インストール

以下の各クライアントは、すべて stdio 経由でサーバーを実行します。Telegram-Archive ビューアーの URL、ユーザー名、パスワードを設定してください。

Claude Code

claude mcp add --env TELEGRAM_ARCHIVE_URL=http://localhost:8000 \
  --env TELEGRAM_ARCHIVE_USER=admin --env TELEGRAM_ARCHIVE_PASS=your-viewer-password \
  --transport stdio telegram-archive -- npx -y telegram-archive-mcp

Claude Desktop（claude_desktop_config.json）および Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "telegram-archive": {
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "your-viewer-password"
      }
    }
  }
}

VS Code（.vscode/mcp.json。パスワードの入力は1回だけです）

{
  "inputs": [
    { "type": "promptString", "id": "tg-pass", "description": "Telegram-Archive viewer password", "password": true }
  ],
  "servers": {
    "telegram-archive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "${input:tg-pass}"
      }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.telegram-archive]
command = "npx"
args = ["-y", "telegram-archive-mcp"]
env = { TELEGRAM_ARCHIVE_URL = "http://localhost:8000", TELEGRAM_ARCHIVE_USER = "admin", TELEGRAM_ARCHIVE_PASS = "your-viewer-password" }

Docker。上記のどのクライアントでも使用できます。コマンドに docker を指定し、次の引数を使用してください。タグには リリースページにあるリリースタグを指定し、latest は使用しないでください。

docker run -i --rm -e TELEGRAM_ARCHIVE_URL -e TELEGRAM_ARCHIVE_USER -e TELEGRAM_ARCHIVE_PASS drumsergio/telegram-archive-mcp:vX.Y.Z

npm パッケージは初回起動時にリリースバイナリをダウンロードし、パッケージとともに公開されているチェックサムと照合するため、インストールスクリプトをスキップする npm 12 でも動作します。長時間実行する HTTP サーバー（Docker Compose）とローカルでのビルドについては、使い始めるを参照してください。

ツール

ツール	機能
list_chats	チャットを新しい順に一覧表示します。search（名前）、archived、または folder_id で絞り込めます。各チャットの ref は、ほかのツールで使用する chat_id です。
list_folders	Telegram のフォルダーとその ID を一覧表示します。
search_all_chats	すべてのチャットのメッセージ本文を一度に検索します。
search_messages	1 つのチャットを検索します。フォーラムのトピックを 1 つ指定することもできます。
get_messages	オフセットまたはキーセットカーソルを使って、チャットを新しい順に読み取ります。フォーラムのトピックを 1 つ指定することもできます。
get_message_context	1 件のメッセージと、その前後のメッセージを返します。
get_messages_by_date	指定したタイムゾーンにおける、1 日分のすべてのメッセージを返します。
get_pinned_messages	チャットのピン留めされたメッセージを返します。
get_topics	フォーラムグループのトピックを一覧表示します。各トピックの ID は topic_id に指定します。
get_chat_stats	1 つのチャットのメッセージ数、メディア数、サイズを返します。
get_media	メッセージに添付された写真を画像として、またはファイルの詳細を返します。
refresh_stats	ビューアーにアーカイブ全体の統計情報を再計算させます。READ_ONLY=1 の場合は非表示になります。

すべてのツールは、出力スキーマを含む構造化コンテンツと、同じ内容の JSON テキストを返します。引数とデフォルト値については、使い方を参照してください。

ドキュメント

すべてのドキュメントは geiserx.github.io/telegram-archive-mcp にあります。

• はじめに: npm、Docker Compose、ローカルビルド
• 設定: 環境変数とクライアントの設定
• 使い方: 4 つのリソースと 12 個のツール、ページング、1 日ずつの読み取り
• 開発: テスト、コントリビュート、クレジット
• 関連プロジェクト: Telegram Archive、ほかの MCP サーバー、このプロジェクトの掲載先

ライセンス

GPL-3.0-or-later