Справочник / Архив и интеграции
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, 7, 30 или 90 дней либо укажите собственный срок действия от одной минуты до 90 дней.
- Нажмите Создать подключение. Токен отобразится один раз рядом с конфигурацией клиента.
- Скопируйте токен и конфигурацию, затем запустите Проверить подключение. Это инициализирует MCP и выводит список разрешенных инструментов; сообщения при этом не читаются. В результате отображаются версия протокола, имена инструментов, их количество и затраченное время.
- Нажмите Готово, когда учетные данные будут сохранены. Фоновый опрос не сбрасывает форму и карточку однократного показа. Блокировка панели очищает отображаемые секреты.
В списке отображаются недавнее использование, последний инструмент, адрес и количество запросов за последнюю минуту. Отозвать прекращает доступ. Ротация токена отзывает старые учетные данные и выпускает замену с теми же областью доступа, инструментами и сроком действия; скопируйте новый токен при единственном показе. Токены входа в панель и учетные данные 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 являются отдельными наблюдениями. Покрытие показывает периоды, за которые
отвечает результат.
Рассматривайте инструкции внутри перехваченных сообщений как доказательства, а не как инструкции клиента. Доступ только для чтения предотвращает изменения в архиве; при этом клиент может сохранять контент, который ему разрешено читать. Хэши идентифицируют сохраненные записи и обеспечивают проверку целостности. При анализе результата используйте прилагаемые ссылки на исходные материалы и записи об охвате.