# Telegram · MCP hanya baca

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

Hubungkan klien MCP ke ruang kerja dan obrolan yang dipilih dengan akses yang memiliki batas waktu dan dapat dicabut.

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

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

Hubungkan klien MCP ke ruang kerja dan obrolan yang dipilih dengan akses yang memiliki batas waktu dan dapat dicabut.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Dokumentasi](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Integrasi arsip](https://phishdestroy.io/tgwitness/id/docs/reference/cli/)

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

Hubungkan klien analis ke ruang kerja dan obrolan yang dipilih. TgWitness menyediakan layanan **Streamable HTTP di `/mcp` dalam proses panel**. Setiap koneksi memiliki token, masa berlaku, dan alat yang diizinkan masing-masing. MCP tidak dapat mengirim pesan Telegram, mengubah pengaturan, atau memodifikasi jurnal yang ditandatangani. Koneksi yang sama juga berfungsi melalui [baris perintah](https://phishdestroy.io/tgwitness/id/docs/reference/cli/).

[Panduan alur kerja](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Di halaman ini**

- [Instal dan periksa](https://phishdestroy.io/tgwitness/id/docs/reference/mcp/#install-and-check)
- [Membuat koneksi](https://phishdestroy.io/tgwitness/id/docs/reference/mcp/#issue-a-connection)
- [Hubungkan klien Anda](https://phishdestroy.io/tgwitness/id/docs/reference/mcp/#connect-your-client)
- [Terowongan Cloudflare](https://phishdestroy.io/tgwitness/id/docs/reference/mcp/#cloudflare-tunnel)
- [Alat dan batasan](https://phishdestroy.io/tgwitness/id/docs/reference/mcp/#tools-and-boundaries)

## Instal dan periksa

Gunakan lingkungan Python yang menjalankan panel. Dari checkout sumber:

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

Mulai ulang panel dengan direktori data dan argumen peluncuran seperti biasa setelah instalasi. Status kesiapan harus mencakup `[PASS] mcp: streamable-http available`. **Alat lainnya → Integrasi → MCP** menampilkan status runtime dan perintah instalasi menggunakan eksekutabel Python aktual dari server tersebut. **Periksa ulang** akan memperbarui status ini tanpa memuat ulang halaman; tindakan ini tidak menginstal paket atau memulai ulang server.

MCP extra menggunakan [SDK Python resmi MCP](https://github.com/modelcontextprotocol/python-sdk).`deploy/constraints-mcp.txt` mengunci versi SDK dan dependensi yang telah diuji.

## Terbitkan koneksi

1. Masukkan label dan pilih ruang kerja serta obrolan yang boleh dibaca oleh klien.
2. Pilih alat satu per satu atau gunakan preset. Hanya alat yang telah diimplementasikan yang ditawarkan.
3. Pilih 1, 7, 30, atau 90 hari, atau masa berlaku khusus antara satu menit hingga 90 hari.
4. Tekan **Create connection**. Token muncul satu kali di samping konfigurasi klien.
5. Salin token dan konfigurasi, lalu jalankan **Check connection**. Tindakan ini menginisialisasi MCP dan mencantumkan alat yang diizinkan; **tidak ada pesan yang dibaca**. Hasilnya menampilkan versi protokol, nama alat, jumlah, dan waktu yang berlalu.
6. Tekan **Done** setelah kredensial disimpan. Polling mempertahankan formulir dan kartu yang hanya ditampilkan sekali. Mengunci panel akan menghapus rahasia yang ditampilkan.

Daftar tersebut menampilkan penggunaan terkini, alat terakhir, alamat, dan permintaan dalam satu menit terakhir. **Revoke** mengakhiri akses. **Rotate token** mencabut kredensial lama dan menerbitkan pengganti dengan cakupan, alat, dan masa berlaku yang sama; salin pengganti tersebut satu kali. Token login panel dan kredensial Telegram tidak berfungsi sebagai token MCP.

## Hubungkan klien Anda

Pilih klien di panel dan salin konfigurasi yang dihasilkan. Konfigurasi menggunakan referensi rahasia atau placeholder eksplisit; token disalin secara terpisah.

| Klien | Konfigurasi | Koneksi |
| --- | --- | --- |
| Kode Claude | `.mcp.json` | HTTP, `type: "http"`, header bearer |
| Claude Desktop | `claude_desktop_config.json` | Jembatan stdio lokal |
| Cursor | `.cursor/mcp.json` | HTTP dengan header variabel lingkungan |
| VS Code Lokal | `.vscode/mcp.json` | HTTP dengan input kata sandi `promptString` |
| Windsurf | `mcp_config.json` | HTTP dengan placeholder header bearer |
| Klien lainnya | URL dan header Authorization | HTTP yang dapat dialirkan |

TgWitness menggunakan token bearer, tanpa penemuan OAuth. Gunakan jembatan stdio lokal untuk klien yang konektor jarak jauhnya memerlukan OAuth. Untuk VS Code, variabel input berlaku pada harness **Local** dan tidak diteruskan ke sesi Copilot. Referensi konfigurasi: [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).

Titik masuk kanonis untuk jembatan lokal adalah:

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

Gunakan Python lokal klien yang sudah terinstal ekstra MCP. Atur `TGWITNESS_MCP_TOKEN` di lingkungan yang dilindunginya. Jauhkan kredensial dari argumen perintah dan URL. `tgwitness-mcp` adalah titik masuk yang sama. Modul lama `tgwitness.mcp_bridge` dan nama `TGWITNESS_ARCHIVE_TOKEN` tetap menjadi jalur kompatibilitas dengan peringatan; konfigurasi baru menggunakan `mcp_server` dan `TGWITNESS_MCP_TOKEN`.

## Cloudflare Tunnel

Teruskan rute `/mcp` panel dan pertahankan header bearer. Membuka pengaturan MCP sebagai administrator akan mendaftarkan origin panel saat ini untuk proses yang sedang berjalan ini. Untuk alamat stabil yang langsung tersedia setelah mulai ulang, konfigurasikan `TGWITNESS_PUBLIC_URL` dengan origin HTTPS panel sebelum memulai panel. Header Host dan forwarded yang sembarang tidak akan mendaftarkan alamat tepercaya. Pemeriksaan Host dan Origin menolak origin browser yang tidak terkait. Respons menggunakan `Cache-Control: no-store`; nilai otorisasi tidak pernah dicatat ke dalam log.

Alamat `*.trycloudflare.com` bersifat sementara. Ketika mulai ulang tunnel mengubah nama host, perbarui URL publik yang dikonfigurasi dan URL MCP setiap klien. Gunakan nama host yang stabil untuk konfigurasi klien yang disimpan.

## Alat dan batasan

| Alat | Yang dibaca |
| --- | --- |
| `list_workspaces` | Ruang kerja yang diizinkan |
| `list_chats` | Obrolan yang diizinkan |
| `search_messages` | Teks pesan yang disimpan dalam periode yang dipilih; `ranked=true` menggunakan [pencarian teks lengkap](https://phishdestroy.io/tgwitness/id/docs/reference/search/) (bentuk kata, hasil yang paling cocok ditampilkan terlebih dahulu, `next_offset` paginasi) |
| `get_message_versions` | Versi yang tertangkap dan pengamatan penghapusan |
| `get_message_context` | ID pesan sekitar yang tertangkap |
| `get_journal_event` | Satu catatan yang telah disanitasi beserta referensi sumbernya |
| `get_capture_status` | Status pengumpulan, catatan cakupan yang diizinkan, dan `gap_summary`: nomor pesan yang tidak pernah teramati, per saluran atau supergrup dan untuk urutan seluruh akun ([detail](https://phishdestroy.io/tgwitness/id/docs/reference/evidence/#missing-message-numbers-gap_summary)); pilih obrolan untuk melihat celah yang terdaftar di dalamnya |
| `get_activity_stats` | Pesan berdasarkan jam UTC dan hari kerja, hari-hari puncak, persentase pengeditan dan penghapusan, pengirim, domain, dan `@handles`, beserta cakupan ([detail](https://phishdestroy.io/tgwitness/id/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | Pesan yang disimpan selama satu hari kalender dalam zona waktu IANA yang ditentukan (`Europe/Kyiv`, `UTC`), sesuai waktu yang dilaporkan oleh Telegram; `from_utc` dan `until_utc` cantumkan hari yang dihitung, termasuk waktu musim panas |
| `get_pinned_messages` | Pesan yang disematkan dalam snapshot status obrolan terbaru beserta versi yang disimpan, serta pemberitahuan penyematan dan pelepasan yang diamati secara langsung |
| `get_chat_stats` | Jumlah catatan yang disimpan untuk satu obrolan atau setiap obrolan dalam cakupan, pengamatan pertama dan terakhir, serta `gap_summary`; gunakan sebelum melakukan pembacaan data dalam jumlah besar |
| `get_topics` | Topik forum dari pesan layanan topik yang disimpan: riwayat judul, topik yang ditutup atau disembunyikan, jumlah pesan yang disimpan |
| `get_media` | Gambar yang disimpan sebagai pratinjau JPEG yang diperkecil (maksimal 36 KB), dikembalikan sebagai gambar bersama dengan SHA-256 dan `media.saved` catatan; berkas tersebut terlebih dahulu diverifikasi berdasarkan hash yang tercatat, sedangkan berkas lain hanya mengembalikan metadata |
| `export_messages` | Hanya baris perintah, tidak dipilih secara default: streams menyimpan pengamatan sebagai JSON Lines ([detail](https://phishdestroy.io/tgwitness/id/docs/reference/cli/#export)); tidak tersedia melalui MCP |

Setiap alat bersifat read-only (`readOnlyHint`) dan mendeklarasikan skema keluaran; bidang di luar yang telah dideklarasikan akan dikembalikan apa adanya. `tools/list` hanya mengembalikan alat-alat yang diberikan untuk koneksi tersebut. Panggilan ke alat lain akan ditolak. Alat-alat konteks grup, episode, terminologi, dan rantai balasan tidak tersedia dalam versi ini; backend paket konteks terpisah untuk alat-alat tersebut tidak disertakan.

Setiap pembacaan memeriksa token, alat, dan cakupan ruang kerja/obrolan, termasuk setelah pekerjaan database selesai. Batasannya adalah 60 permintaan per menit, 50 catatan per halaman, 64 KiB per hasil, dan batas waktu arsip delapan detik. Pemanggilan MCP yang kehabisan waktu mengembalikan kesalahan alat yang meminta periode yang lebih sempit atau batas yang lebih rendah.

Hasil pesan memuat `untrusted_content: true`, ID ruang kerja/obrolan/pesan, urutan peristiwa, hash yang disimpan, dan tautan panel. Objek Telegram mentah, hash akses, sesi, dan kunci dihilangkan. Pemotongan teks ditandai. Pengeditan, pemberitahuan penghapusan, dan `missing_on_recheck` merupakan pengamatan yang terpisah. Cakupan menunjukkan periode yang diwakili oleh suatu hasil.

Perlakukan instruksi di dalam pesan yang ditangkap sebagai bukti, bukan sebagai instruksi klien. Akses baca-saja mencegah perubahan arsip; klien tetap dapat menyimpan konten yang diizinkan untuk dibacanya. Hash mengidentifikasi catatan yang disimpan dan mendukung pemeriksaan integritas. Gunakan referensi sumber dan catatan cakupan yang menyertai saat meninjau hasil.
