# Telegram · MCP тільки для читання

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

Підключіть клієнт MCP до вибраних робочих просторів та чатів із тимчасовим, відкличним доступом.

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

[Documentation index](https://phishdestroy.io/tgwitness/uk/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/uk/docs/reference/cli/)

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

Підключіть клієнт-аналітик до вибраних робочих просторів та чатів. TgWitness надає доступ до **Streamable HTTP за адресою `/mcp` у процесі панелі**. Кожне з’єднання має власний токен, термін дії та дозволені інструменти. MCP не може надсилати повідомлення Telegram, змінювати налаштування або модифікувати підписаний журнал. Ці ж з’єднання працюють із [командним рядком](https://phishdestroy.io/tgwitness/uk/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/uk/docs/reference/mcp/#install-and-check)
- [Встановити з’єднання](https://phishdestroy.io/tgwitness/uk/docs/reference/mcp/#issue-a-connection)
- [Підключіть свій клієнт](https://phishdestroy.io/tgwitness/uk/docs/reference/mcp/#connect-your-client)
- [Тунель Cloudflare](https://phishdestroy.io/tgwitness/uk/docs/reference/mcp/#cloudflare-tunnel)
- [Інструменти та обмеження](https://phishdestroy.io/tgwitness/uk/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. Натисніть **Create connection**. Токен з’явиться один раз поруч із конфігурацією клієнта.
5. Скопіюйте токен і конфігурацію, а потім натисніть **Check connection**. Це ініціалізує MCP і виведе список дозволених інструментів; **жодні повідомлення не читаються**. Результат показує версію протоколу, назви інструментів, їхню кількість і витрачений час.
6. Натисніть **Done**, коли облікові дані буде збережено. Фонове опитування зберігає форму та картку одноразового показу. Блокування панелі очищає відображені секретні дані.

У списку відображаються нещодавнє використання, останній інструмент, адреса та запити за останню хвилину. **Revoke** припиняє доступ. **Rotate token** відкликає старі облікові дані та видає заміну з тією самою областю дії, інструментами та терміном дії; скопіюйте новий токен (він показується один раз). Токени входу в панель та облікові дані 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) панелі для цього запуску. Щоб стабільна адреса була доступна одразу після перезапуску, налаштуйте `TGWITNESS_PUBLIC_URL` із HTTPS-джерелом панелі перед її запуском. Довільні заголовки Host і заголовки перенаправлення не реєструють довірену адресу. Перевірки Host і Origin відхиляють сторонні джерела браузера. Відповіді використовують `Cache-Control: no-store`; значення авторизації ніколи не записуються в журнал.

Адреса `*.trycloudflare.com` є тимчасовою. Коли перезапуск тунелю змінює ім’я хоста, оновіть налаштовану публічну URL-адресу та URL-адресу MCP кожного клієнта. Використовуйте стабільне ім’я хоста для збережених конфігурацій клієнтів.

## Інструменти та обмеження

| Інструмент | Що читає |
| --- | --- |
| `list_workspaces` | Дозволені робочі простори |
| `list_chats` | Дозволені чати |
| `search_messages` | Текст збережених повідомлень за вибраний період; `ranked=true` використовує [повнотекстовий пошук](https://phishdestroy.io/tgwitness/uk/docs/reference/search/) (форми слів, найкращі збіги першими, `next_offset` пагінація) |
| `get_message_versions` | Зафіксовані версії та спостереження щодо видалення |
| `get_message_context` | Сусідні ідентифікатори зафіксованих повідомлень |
| `get_journal_event` | Один очищений запис із посиланням на його джерело |
| `get_capture_status` | Стан збору даних, дозволені записи охоплення та `gap_summary`: номери повідомлень, які ніколи не спостерігалися, за кожним каналом або супергрупою, а також для послідовності в межах усього облікового запису ([деталі](https://phishdestroy.io/tgwitness/uk/docs/reference/evidence/#missing-message-numbers-gap_summary)); виберіть чат, щоб переглянути перелік пропусків у ньому |
| `get_activity_stats` | Повідомлення за годинами за UTC та днями тижня, дні пікового навантаження, частка редагувань та видалень, відправники, домени та `@handles`, із охопленням ([деталі](https://phishdestroy.io/tgwitness/uk/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` | Тільки командний рядок, не вибрано за замовчуванням: потоки зберігають спостереження у форматі JSON Lines ([деталі](https://phishdestroy.io/tgwitness/uk/docs/reference/cli/#export)); не доступно через MCP |

Кожен інструмент працює лише в режимі читання (`readOnlyHint`) і оголошує схему виводу; поля, що виходять за межі оголошених, повертаються без змін. `tools/list` Повертає лише ті інструменти, доступ до яких надано для цього з’єднання. Виклики інших інструментів відхиляються. Інструменти групового контексту, епізоду, термінології та ланцюга відповідей у цій збірці не доступні; їхній окремий бекенд context-pack не включено.

Кожне читання перевіряє токен, інструмент та область дії робочого простору/чату, зокрема після завершення роботи з базою даних. Обмеження становлять 60 запитів на хвилину, 50 записів на сторінку, 64 КіБ на результат і восьмисекундний граничний час очікування архіву. Виклик MCP, час очікування якого минув, повертає помилку інструмента з проханням звузити період або зменшити ліміт.

Результати повідомлень містять `untrusted_content: true`, ідентифікатори робочого простору/чату/повідомлення, послідовність подій, збережений хеш та посилання на панель. Необроблені об’єкти Telegram, хеші доступу, сесії та ключі опускаються. Скорочення тексту позначається. Редагування, повідомлення про видалення та `missing_on_recheck` є окремими спостереженнями. Покриття показує періоди, за які відповідає результат.

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