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

Canonical page: https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/ru/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/ru/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Документация](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Интеграция с архивами](https://phishdestroy.io/tgwitness/ru/docs/reference/cli/)

![Интеграция с архивами](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

Подключите клиент аналитика к выбранным рабочим пространствам и чатам. TgWitness предоставляет доступ к **Streamable HTTP по адресу `/mcp` в процессе панели**. Каждое соединение имеет свой собственный токен, срок действия и разрешённые инструменты. MCP не может отправлять сообщения в Telegram, изменять настройки или модифицировать подписанный журнал. Те же соединения работают с [командной строкой](https://phishdestroy.io/tgwitness/ru/docs/reference/cli/).

[Руководство по рабочему процессу](https://phishdestroy.io/tgwitness/docs/archive/) · [Вики](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

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

- [Установка и проверка](https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/#install-and-check)
- [Установить соединение](https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/#issue-a-connection)
- [Подключите свой клиент](https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/#connect-your-client)
- [Cloudflare Tunnel](https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/#cloudflare-tunnel)
- [Инструменты и ограничения](https://phishdestroy.io/tgwitness/ru/docs/reference/mcp/#tools-and-boundaries)

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

Используйте окружение 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](https://github.com/modelcontextprotocol/python-sdk). Файл`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](https://code.claude.com/docs/en/mcp), [Cursor](https://prod.cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

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

```
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` поддерживает [полнотекстовый поиск](https://phishdestroy.io/tgwitness/ru/docs/reference/search/) (формы слов, сначала отображаются наиболее подходящие результаты, `next_offset` пагинация) |
| `get_message_versions` | Зафиксированные версии и наблюдения об удалении |
| `get_message_context` | Идентификаторы соседних зафиксированных сообщений |
| `get_journal_event` | Одна очищенная запись со ссылкой на источник |
| `get_capture_status` | Состояние сбора данных, разрешенные записи о охвате и `gap_summary`: номера сообщений, которые никогда не наблюдались, по каждому каналу или супергруппе, а также для всей последовательности аккаунта ([подробнее](https://phishdestroy.io/tgwitness/ru/docs/reference/evidence/#missing-message-numbers-gap_summary)); выберите чат, чтобы увидеть перечень пробелов в нём |
| `get_activity_stats` | Сообщения по часам UTC и дням недели, дни пиковой активности, доля отредактированных и удалённых сообщений, отправители, домены и `@handles`, с охватом ([подробности](https://phishdestroy.io/tgwitness/ru/docs/reference/cli/#activity-statistics)) |
| `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 ([подробности](https://phishdestroy.io/tgwitness/ru/docs/reference/cli/#export)); не предлагается через MCP |

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

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

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

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