# Telegram · MCP tylko do odczytu

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

Połącz klienta MCP z wybranymi obszarami roboczymi i czatami, korzystając z dostępu ograniczonego czasowo i podlegającego odwołaniu.

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

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

Połącz klienta MCP z wybranymi obszarami roboczymi i czatami, korzystając z dostępu ograniczonego czasowo i podlegającego odwołaniu.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Dokumentacja](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Integracje z archiwami](https://phishdestroy.io/tgwitness/pl/docs/reference/cli/)

![Integracje z archiwami](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

Połącz klienta analitycznego z wybranymi obszarami roboczymi i czatami. TgWitness udostępnia **protokół Streamable HTTP pod adresem `/mcp` w procesie panelowym**. Każde połączenie ma swój własny token, termin ważności oraz zestaw dozwolonych narzędzi. MCP nie może wysyłać wiadomości w Telegramie, zmieniać ustawień ani modyfikować podpisanego dziennika. Te same połączenia działają również z [wierszem poleceń](https://phishdestroy.io/tgwitness/pl/docs/reference/cli/).

[Przewodnik po procesie pracy](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Na tej stronie**

- [Instalacja i sprawdzenie](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/#install-and-check)
- [Nawiązanie połączenia](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/#issue-a-connection)
- [Podłącz swojego klienta](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/#connect-your-client)
- [Tunel Cloudflare](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/#cloudflare-tunnel)
- [Narzędzia i ograniczenia](https://phishdestroy.io/tgwitness/pl/docs/reference/mcp/#tools-and-boundaries)

## Instalacja i weryfikacja

Użyj środowiska Python, w którym działa panel. Z pobranego kodu źródłowego wykonaj:

```
# 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
```

Po instalacji uruchom ponownie panel, podając jego standardowy katalog danych i argumenty uruchomieniowe. Gotowość powinna obejmować komunikat `[PASS] mcp: streamable-http available`. W sekcji **Więcej narzędzi → Integracje → MCP** wyświetlany jest stan środowiska uruchomieniowego oraz polecenie instalacyjne wykorzystujące rzeczywisty plik wykonywalny języka Python tego serwera. **Opcja Sprawdź ponownie** odświeża ten stan bez ponownego ładowania strony; nie powoduje ona instalacji pakietów ani ponownego uruchomienia serwera.

Dodatek MCP korzysta z oficjalnego zestawu [SDK MCP dla języka Python](https://github.com/modelcontextprotocol/python-sdk). Plik`deploy/constraints-mcp.txt` określa wersję testowanego zestawu SDK i zależności.

## Utworzenie połączenia

1. Wprowadź etykietę oraz wybierz obszary robocze i czaty, które klient może odczytywać.
2. Wybierz narzędzia pojedynczo lub użyj presetu. Dostępne są tylko zaimplementowane narzędzia.
3. Wybierz 1, 7, 30 lub 90 dni albo własny czas wygaśnięcia z przedziału od jednej minuty do 90 dni.
4. Naciśnij **Create connection**. Token wyświetli się jednorazowo obok konfiguracji klienta.
5. Skopiuj token i konfigurację, a następnie uruchom **Check connection**. Inicjalizuje to MCP i wyświetla listę dozwolonych narzędzi; **żadne wiadomości nie są odczytywane**. Wynik pokazuje wersję protokołu, nazwy narzędzi, ich liczbę oraz czas wykonania.
6. Naciśnij **Done** po zapisaniu poświadczeń. Odpytywanie w tle zachowuje formularz oraz kartę wyświetlaną jednorazowo. Zablokowanie panelu czyści wyświetlone sekrety.

Lista pokazuje ostatnie użycie, ostatnie narzędzie, adres oraz liczbę żądań w ciągu ostatniej minuty. **Revoke** kończy dostęp. **Rotate token** unieważnia stare poświadczenie i wydaje nowe z tym samym zakresem, zestawem narzędzi i czasem wygaśnięcia; skopiuj nowy token (wyświetlany jednorazowo). Tokeny logowania do panelu oraz poświadczenia Telegrama nie działają jako tokeny MCP.

## Podłączanie klienta

Wybierz klienta w panelu i skopiuj wygenerowaną dla niego konfigurację. Konfiguracje używają odwołań do sekretów lub jawnych symboli zastępczych (placeholderów); token jest kopiowany osobno.

| Klient | Konfiguracja | Połączenie |
| --- | --- | --- |
| Kod Claude'a | `.mcp.json` | HTTP, `type: "http"`, nagłówek bearer |
| Claude Desktop | `claude_desktop_config.json` | Lokalny mostek stdio |
| Cursor | `.cursor/mcp.json` | HTTP z nagłówkiem opartym na zmiennej środowiskowej |
| VS Code Local | `.vscode/mcp.json` | HTTP z wprowadzaniem hasła typu `promptString` |
| Windsurf | `mcp_config.json` | HTTP z symbolem zastępczym nagłówka bearer |
| Inni klienci | Adres URL i nagłówek Authorization | Strumieniowy protokół HTTP |

TgWitness używa tokenów bearer bez wykrywania OAuth. Użyj lokalnego mostka stdio dla klientów, których zdalny konektor wymaga OAuth. W przypadku VS Code zmienne wejściowe mają zastosowanie do środowiska **Local** i nie są przekazywane do sesji Copilot. Dokumentacja konfiguracji: [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).

Kanoniczny punkt wejścia dla lokalnego mostka to:

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

Użyj lokalnego środowiska Python klienta z zainstalowanym dodatkiem MCP. Ustaw zmienną `TGWITNESS_MCP_TOKEN` w jego chronionym środowisku. Nie umieszczaj poświadczeń w argumentach poleceń ani w adresach URL. `tgwitness-mcp` to ten sam punkt wejścia. Stary moduł `tgwitness.mcp_bridge` oraz nazwa `TGWITNESS_ARCHIVE_TOKEN` pozostają ścieżkami zgodności z ostrzeżeniem; nowe konfiguracje używają `mcp_server` oraz `TGWITNESS_MCP_TOKEN`.

## Cloudflare Tunnel

Przekieruj ścieżkę `/mcp` panelu i zachowaj nagłówek bearer. Otwarcie ustawień MCP jako administrator rejestruje bieżący origin panelu dla danego uruchomienia. Aby uzyskać stabilny adres dostępny natychmiast po restarcie, skonfiguruj zmienną `TGWITNESS_PUBLIC_URL` z adresem origin HTTPS panelu przed jego uruchomieniem. Dowolne nagłówki Host i nagłówki przekazywane (forwarded) nie rejestrują zaufanego adresu. Weryfikacja nagłówków Host i Origin odrzuca niepowiązane adresy pochodzenia przeglądarki. Odpowiedzi używają `Cache-Control: no-store`; wartości autoryzacyjne nigdy nie są logowane.

Adres `*.trycloudflare.com` jest tymczasowy. Gdy restart tunelu zmieni nazwę hosta, zaktualizuj skonfigurowany publiczny adres URL oraz adres URL MCP u każdego klienta. Używaj stabilnej nazwy hosta dla zapisanych konfiguracji klientów.

## Narzędzia i ograniczenia

| Narzędzie | Odczytuje |
| --- | --- |
| `list_workspaces` | Przyznane obszary robocze |
| `list_chats` | Przyznane czaty |
| `search_messages` | Tekst zapisanych wiadomości z wybranego okresu; `ranked=true` wykorzystuje [wyszukiwanie pełnotekstowe](https://phishdestroy.io/tgwitness/pl/docs/reference/search/) (formy słów, najpierw najlepsze dopasowania, `next_offset` stronicowanie) |
| `get_message_versions` | Przechwycone wersje i obserwacje usunięć |
| `get_message_context` | Identyfikatory pobliskich przechwyconych wiadomości |
| `get_journal_event` | Jeden oczyszczony rekord wraz z odwołaniem do źródła |
| `get_capture_status` | Stan zbioru, dozwolone zapisy dotyczące zasięgu oraz `gap_summary`: numery wiadomości, których nigdy nie zaobserwowano, w podziale na kanały lub supergrupy oraz dla sekwencji obejmującej całe konto ([szczegóły](https://phishdestroy.io/tgwitness/pl/docs/reference/evidence/#missing-message-numbers-gap_summary)); wybierz czat, aby wyświetlić listę luk w danych |
| `get_activity_stats` | Wiadomości według godziny UTC i dnia tygodnia, dni o największym natężeniu ruchu, odsetek edycji i usunięć, nadawców, domen oraz `@handles`, wraz z zasięgiem ([szczegóły](https://phishdestroy.io/tgwitness/pl/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | Zapisane wiadomości z jednego dnia kalendarzowego w określonej strefie czasowej IANA (`Europe/Kyiv`, `UTC`), według czasu zgłaszanego przez Telegram; `from_utc` oraz `until_utc` należy podać obliczony dzień, z uwzględnieniem czasu letniego |
| `get_pinned_messages` | Wiadomości przypięte w najnowszej migawce stanu czatu wraz z ich zapisanymi wersjami oraz powiadomienia o przypięciu i odpięciu obserwowane na żywo |
| `get_chat_stats` | Liczba zapisanych rekordów dla jednej rozmowy lub wszystkich rozmów objętych zakresem, pierwsza i ostatnia obserwacja oraz `gap_summary`; należy z niego skorzystać przed przeprowadzeniem operacji odczytu dużej ilości danych |
| `get_topics` | Wątki na forum z wiadomości z usługi zapisanych wątków: historia tytułów, wątki zamknięte lub ukryte, liczba zapisanych wiadomości |
| `get_media` | Zachowany obraz w postaci pomniejszonego podglądu w formacie JPEG (maksymalnie 36 KB), zwracany jako obraz wraz z jego skrótem SHA-256 oraz `media.saved` rekordem; plik jest najpierw porównywany z zarejestrowanym skrótem, natomiast w przypadku innych plików zwracane są wyłącznie metadane |
| `export_messages` | Działa wyłącznie z wiersza poleceń, domyślnie nie jest zaznaczone: strumieniowo zapisuje obserwacje w formacie JSON Lines ([szczegóły](https://phishdestroy.io/tgwitness/pl/docs/reference/cli/#export)); nie jest dostępne za pośrednictwem MCP |

Każde narzędzie jest tylko do odczytu (`readOnlyHint`) i deklaruje schemat wyjściowy; pola wykraczające poza zadeklarowane są zwracane w niezmienionej postaci. `tools/list` Zwraca wyłącznie narzędzia przypisane do danego połączenia. Wywołania innych narzędzi są odrzucane. Narzędzia związane z kontekstem grupy, epizodem, terminologią i łańcuchem odpowiedzi nie są dostępne w tej kompilacji; nie zawiera ona oddzielnego backendu pakietu kontekstowego.

Każdy odczyt weryfikuje token, narzędzie oraz zakres obszaru roboczego/czatu, w tym również po zakończeniu pracy bazy danych. Limity wynoszą 60 żądań na minutę, 50 rekordów na stronę, 64 KiB na wynik oraz osiem sekund limitu czasu operacji w archiwum. Przekroczenie czasu wywołania MCP zwraca błąd narzędzia z prośbą o zawężenie okresu lub zmniejszenie limitu.

Wyniki wiadomości zawierają `untrusted_content: true`, identyfikatory obszaru roboczego/czatu/wiadomości, sekwencję zdarzeń, zapisany skrót oraz link do panelu. Pomija się surowe obiekty Telegramu, skróty dostępu, sesje i klucze. Skrócenia tekstu są oznaczone. Edycje, powiadomienia o usunięciu oraz `missing_on_recheck` stanowią odrębne obserwacje. Zakres pokazuje okresy, które obejmuje dany wynik.

Traktuj instrukcje zawarte w przechwyconych wiadomościach jako dowody, a nie jako instrukcje klienta. Dostęp tylko do odczytu uniemożliwia wprowadzanie zmian w archiwum; klient może jednak zachować treści, do których ma uprawnienia odczytu. Skróty identyfikują zapisane rekordy i wspierają kontrole integralności. Podczas przeglądania wyników korzystaj z dołączonych odniesień do źródeł oraz rekordów pokrycia.
