TgWitness / Документация

Что проверено →

Справочник / Архив и интеграции

MCP-сервер архива Telegram: доступ только для чтения

Подключите клиент MCP к выбранным рабочим пространствам и чатам с ограниченным по времени и отзывным доступом.

TgWitness / Документация · Интеграция с архивами

Интеграция с архивами

Подключите клиент аналитика к выбранным рабочим пространствам и чатам. TgWitness предоставляет доступ к Streamable HTTP по адресу /mcp в процессе панели. Каждое соединение имеет свой собственный токен, срок действия и разрешённые инструменты. MCP не может отправлять сообщения в Telegram, изменять настройки или модифицировать подписанный журнал. Те же соединения работают с командной строкой.

Руководство по рабочему процессу · Вики

На этой странице

Установка и проверка#

Используйте окружение Python, в котором запущена панель. Из каталога с исходным кодом выполните:

# Windows PowerShell
& .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
& .\.venv\Scripts\python.exe start.py --check
# Linux / macOS
.venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
.venv/bin/python start.py --check

После установки перезапустите панель с указанием обычного каталога данных и аргументов запуска. Готовность должна отображаться как [PASS] mcp: streamable-http available. В разделе Дополнительные инструменты → Интеграции → MCP отображается статус работы и команда установки с использованием фактического исполняемого файла Python данного сервера. Кнопка Перепроверить обновляет этот статус без перезагрузки страницы; она не устанавливает пакеты и не перезапускает сервер.

Дополнение MCP использует официальный SDK MCP для Python. Файлdeploy/constraints-mcp.txt фиксирует версию тестируемого SDK и зависимостей.

Выпуск подключения#

  1. Введите метку и выберите рабочие пространства и чаты, которые клиент может читать.
  2. Выберите инструменты по отдельности или используйте пресет. Предлагаются только реализованные инструменты.
  3. Выберите 1, 7, 30 или 90 дней либо укажите собственный срок действия от одной минуты до 90 дней.
  4. Нажмите Создать подключение. Токен отобразится один раз рядом с конфигурацией клиента.
  5. Скопируйте токен и конфигурацию, затем запустите Проверить подключение. Это инициализирует MCP и выводит список разрешенных инструментов; сообщения при этом не читаются. В результате отображаются версия протокола, имена инструментов, их количество и затраченное время.
  6. Нажмите Готово, когда учетные данные будут сохранены. Фоновый опрос не сбрасывает форму и карточку однократного показа. Блокировка панели очищает отображаемые секреты.

В списке отображаются недавнее использование, последний инструмент, адрес и количество запросов за последнюю минуту. Отозвать прекращает доступ. Ротация токена отзывает старые учетные данные и выпускает замену с теми же областью доступа, инструментами и сроком действия; скопируйте новый токен при единственном показе. Токены входа в панель и учетные данные Telegram не работают как токены MCP.

Подключение клиента#

Выберите клиент в панели и скопируйте сгенерированную для него конфигурацию. В конфигурациях используются ссылки на секреты или явные заполнители; сам токен копируется отдельно.

Клиент Конфигурация Связь
Код Claude .mcp.json HTTP, type: "http", заголовок Bearer
Claude Desktop claude_desktop_config.json Локальный stdio-мост
Cursor .cursor/mcp.json HTTP с заголовком из переменной окружения
VS Code Local .vscode/mcp.json HTTP с вводом пароля через promptString
Windsurf mcp_config.json HTTP с заполнителем для заголовка Bearer
Другие клиенты URL и заголовок Authorization Потоковый HTTP

TgWitness использует Bearer-токены без обнаружения OAuth. Используйте локальный stdio-мост для клиентов, чей удаленный коннектор требует OAuth. В VS Code переменные ввода применяются к окружению Local и не передаются в сессии Copilot. Справочники по конфигурации: Claude Code, Cursor, VS Code.

Каноническая точка входа для локального моста:

python -m tgwitness.mcp_server --url https://your-panel.example/mcp

Используйте локальный Python клиента с установленным дополнением MCP. Задайте переменную TGWITNESS_MCP_TOKEN в его защищенном окружении. Не передавайте учетные данные в аргументах командной строки и URL. tgwitness-mcp — это та же самая точка входа. Старый модуль tgwitness.mcp_bridge и имя TGWITNESS_ARCHIVE_TOKEN сохранены для обратной совместимости и выводят предупреждение; в новых конфигурациях используются mcp_server и TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Пробросьте маршрут панели /mcp и сохраните заголовок Bearer. Открытие настроек MCP под учетной записью администратора регистрирует текущий источник (origin) панели для текущего запуска. Чтобы получить стабильный адрес, доступный сразу после перезапуска, укажите HTTPS-источник панели в TGWITNESS_PUBLIC_URL перед ее запуском. Произвольные заголовки Host и заголовки пересылки не регистрируют доверенный адрес. Проверки Host и Origin отклоняют сторонние браузерные источники. В ответах используется Cache-Control: no-store; значения авторизации никогда не записываются в журнал.

Адрес вида *.trycloudflare.com является временным. Если при перезапуске туннеля меняется имя хоста, обновите настроенный публичный URL и URL MCP в каждом клиенте. Используйте стабильное имя хоста для сохраненных клиентских конфигураций.

Инструменты и ограничения#

Инструмент Что читает
list_workspaces Разрешенные рабочие пространства
list_chats Разрешенные чаты
search_messages Текст сохраненных сообщений за выбранный период; ranked=true поддерживает полнотекстовый поиск (формы слов, сначала отображаются наиболее подходящие результаты, next_offset пагинация)
get_message_versions Зафиксированные версии и наблюдения об удалении
get_message_context Идентификаторы соседних зафиксированных сообщений
get_journal_event Одна очищенная запись со ссылкой на источник
get_capture_status Состояние сбора данных, разрешенные записи о охвате и gap_summary: номера сообщений, которые никогда не наблюдались, по каждому каналу или супергруппе, а также для всей последовательности аккаунта (подробнее); выберите чат, чтобы увидеть перечень пробелов в нём
get_activity_stats Сообщения по часам UTC и дням недели, дни пиковой активности, доля отредактированных и удалённых сообщений, отправители, домены и @handles, с охватом (подробности)
get_messages_by_date Сохраненные сообщения за один календарный день в указанном часовом поясе IANA (Europe/Kyiv, UTC), согласно времени, указанному Telegram; from_utc и until_utc укажите рассчитанный день с учётом перехода на летнее время
get_pinned_messages Сообщения, закреплённые в последнем снимке состояния чата, с их сохраненными версиями, а также уведомления о закреплении и снятии закрепления, отображаемые в режиме реального времени
get_chat_stats Укажите количество сохраненных записей для одного чата или всех чатов в области действия, первое и последнее наблюдение, а также gap_summary; используйте его перед операцией чтения большого объема данных
get_topics Темы форума из сообщений службы сохраненных тем: история названий, закрытые или скрытые темы, количество сохраненных сообщений
get_media Сохраненное изображение в виде уменьшенного предварительного просмотра в формате JPEG (не более 36 КБ), возвращаемое в виде изображения вместе с его SHA-256 и media.saved записью; файл сначала сверяется с его записанным хешем, другие файлы возвращают только метаданные
export_messages Только командная строка, не выбрано по умолчанию: streams сохраняет наблюдения в формате JSON Lines (подробности); не предлагается через MCP

Каждый инструмент доступен только для чтения (readOnlyHint) и объявляет схему вывода; поля, выходящие за пределы объявленных, возвращаются без изменений. tools/list Возвращаются только те инструменты, доступ к которым предоставлен данному соединению. Вызовы других инструментов отклоняются. Инструменты группового контекста, эпизода, терминологии и цепочки ответов в данной сборке не доступны; их отдельный бэкенд context-pack не включён.

Каждая операция чтения проверяет токен, инструмент и область доступа к рабочему пространству или чату, в том числе после завершения работы с базой данных. Действуют ограничения: 60 запросов в минуту, 50 записей на страницу, 64 КиБ на результат и восьмисекундный лимит времени на обращение к архиву. При превышении времени ожидания вызов MCP возвращает ошибку инструмента с просьбой сузить период или уменьшить лимит.

Результаты сообщений содержат untrusted_content: true, идентификаторы рабочей области/чата/сообщения, последовательность событий, сохраненный хеш и ссылку на панель. Исходные объекты Telegram, хеши доступа, сессии и ключи опускаются. Усечение текста отмечается. Редактирования, уведомления об удалении и missing_on_recheck являются отдельными наблюдениями. Покрытие показывает периоды, за которые отвечает результат.

Рассматривайте инструкции внутри перехваченных сообщений как доказательства, а не как инструкции клиента. Доступ только для чтения предотвращает изменения в архиве; при этом клиент может сохранять контент, который ему разрешено читать. Хэши идентифицируют сохраненные записи и обеспечивают проверку целостности. При анализе результата используйте прилагаемые ссылки на исходные материалы и записи об охвате.