# Telegram · MCP di sola lettura

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

Collega un client MCP agli spazi di lavoro e alle chat selezionati con un accesso a scadenza e revocabile.

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

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

Collega un client MCP agli spazi di lavoro e alle chat selezionati con un accesso a scadenza e revocabile.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentazione](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Integrazioni con gli archivi](https://phishdestroy.io/tgwitness/it/docs/reference/cli/)

![Integrazioni con gli archivi](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

Collegare un client di analisi a spazi di lavoro e chat selezionati. TgWitness fornisce un servizio **HTTP Streamable all'indirizzo `/mcp` nel processo del pannello**. Ogni connessione dispone di un proprio token, una scadenza e strumenti consentiti. MCP non può inviare messaggi Telegram, modificare le impostazioni né alterare il registro firmato. Le stesse connessioni funzionano anche dalla [riga di comando](https://phishdestroy.io/tgwitness/it/docs/reference/cli/).

[Guida al flusso di lavoro](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**In questa pagina**

- [Installazione e verifica](https://phishdestroy.io/tgwitness/it/docs/reference/mcp/#install-and-check)
- [Stabilire una connessione](https://phishdestroy.io/tgwitness/it/docs/reference/mcp/#issue-a-connection)
- [Connetti il tuo client](https://phishdestroy.io/tgwitness/it/docs/reference/mcp/#connect-your-client)
- [Tunnel Cloudflare](https://phishdestroy.io/tgwitness/it/docs/reference/mcp/#cloudflare-tunnel)
- [Strumenti e limiti](https://phishdestroy.io/tgwitness/it/docs/reference/mcp/#tools-and-boundaries)

## Installa e verifica

Usa l'ambiente Python che esegue il pannello. Da un checkout dei sorgenti:

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

Riavviare il pannello con la sua consueta directory dei dati e gli argomenti di avvio dopo l’ installazione. Lo stato di prontezza dovrebbe includere `[PASS] mcp: streamable-http available`. **Strumenti → Integrazioni → MCP** mostra lo stato di esecuzione e un comando di installazione che utilizza l’eseguibile Python effettivo di quel server. **La funzione Ricontrolla** aggiorna questo stato senza ricaricare la pagina; non installa pacchetti né riavvia il server.

L'extra MCP utilizza [l'SDK Python ufficiale di MCP](https://github.com/modelcontextprotocol/python-sdk).`deploy/constraints-mcp.txt` specifica la versione dell'SDK testato e delle dipendenze.

## Emetti una connessione

1. Inserisci un'etichetta e scegli gli spazi di lavoro e le chat che il client può leggere.
2. Seleziona gli strumenti singolarmente o usa un preset. Vengono offerti solo gli strumenti implementati.
3. Scegli 1, 7, 30 o 90 giorni, oppure una scadenza personalizzata compresa tra un minuto e 90 giorni.
4. Premi **Create connection**. Il token viene mostrato una sola volta accanto alla configurazione del client.
5. Copia il token e la configurazione, quindi esegui **Check connection**. Questo inizializza MCP ed elenca gli strumenti consentiti; **non viene letto alcun messaggio**. Il risultato mostra la versione del protocollo, i nomi degli strumenti, il conteggio e il tempo trascorso.
6. Premi **Done** una volta salvata la credenziale. Il polling preserva il modulo e la scheda mostrata una sola volta. Il blocco del pannello cancella i segreti visualizzati.

L'elenco mostra l'utilizzo recente, l'ultimo strumento, l'indirizzo e le richieste nell'ultimo minuto. **Revoke** interrompe l'accesso. **Rotate token** revoca la vecchia credenziale e ne emette una sostitutiva con lo stesso ambito, gli stessi strumenti e la stessa scadenza; copia il token sostitutivo quando viene mostrato. I token di accesso al pannello e le credenziali di Telegram non funzionano come token MCP.

## Connetti il tuo client

Seleziona il client nel pannello e copia la configurazione generata. Le configurazioni utilizzano riferimenti a segreti o segnaposto espliciti; il token viene copiato separatamente.

| Client | Configurazione | Collegamento |
| --- | --- | --- |
| Claude Code | `.mcp.json` | HTTP, `type: "http"`, header bearer |
| Claude Desktop | `claude_desktop_config.json` | Bridge stdio locale |
| Cursor | `.cursor/mcp.json` | HTTP con header tramite variabile d'ambiente |
| VS Code Local | `.vscode/mcp.json` | HTTP con un input password `promptString` |
| Windsurf | `mcp_config.json` | HTTP con segnaposto per l'header bearer |
| Altri client | URL e header Authorization | HTTP streamabile |

TgWitness utilizza token bearer, senza rilevamento OAuth. Usa il bridge stdio locale per i client il cui connettore remoto richiede OAuth. Per VS Code, le variabili di input si applicano all'ambiente **Local** e non vengono inoltrate alle sessioni di Copilot. Riferimenti per la configurazione: [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).

Il punto di ingresso canonico per un bridge locale è:

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

Usa il Python locale del client con l'extra MCP installato. Imposta `TGWITNESS_MCP_TOKEN` nel suo ambiente protetto. Mantieni le credenziali fuori dagli argomenti dei comandi e dagli URL. `tgwitness-mcp` è lo stesso punto di ingresso. Il vecchio modulo `tgwitness.mcp_bridge` e il nome `TGWITNESS_ARCHIVE_TOKEN` rimangono percorsi di compatibilità che generano un avviso; le nuove configurazioni usano `mcp_server` e `TGWITNESS_MCP_TOKEN`.

## Cloudflare Tunnel

Inoltra la rotta `/mcp` del pannello e preserva l'header bearer. L'apertura delle impostazioni MCP come amministratore registra l'origine corrente del pannello per l'esecuzione in corso. Per avere un indirizzo stabile immediatamente disponibile dopo il riavvio, configura `TGWITNESS_PUBLIC_URL` con l'origine HTTPS del pannello prima di avviarlo. Header Host e di inoltro arbitrari non registrano un indirizzo attendibile. I controlli su Host e Origin rifiutano origini del browser non correlate. Le risposte usano `Cache-Control: no-store`; i valori di autorizzazione non vengono mai registrati nei log.

Un indirizzo `*.trycloudflare.com` è temporaneo. Quando il riavvio di un tunnel modifica l'hostname, aggiorna l'URL pubblico configurato e l'URL MCP di ciascun client. Usa un hostname stabile per le configurazioni salvate dei client.

## Strumenti e limiti

| Strumento | Cosa legge |
| --- | --- |
| `list_workspaces` | Spazi di lavoro autorizzati |
| `list_chats` | Chat autorizzate |
| `search_messages` | Testo dei messaggi salvati nel periodo selezionato; `ranked=true` utilizza [la ricerca full-text](https://phishdestroy.io/tgwitness/it/docs/reference/search/) (forme delle parole, risultati più pertinenti per primi, `next_offset` impaginazione) |
| `get_message_versions` | Versioni acquisite e osservazioni di eliminazione |
| `get_message_context` | ID dei messaggi acquisiti circostanti |
| `get_journal_event` | Un record sanificato con il relativo riferimento alla fonte |
| `get_capture_status` | Stato della raccolta, record di copertura consentiti e `gap_summary`: numeri di messaggi mai osservati, per canale o supergruppo e per la sequenza a livello di account ([dettagli](https://phishdestroy.io/tgwitness/it/docs/reference/evidence/#missing-message-numbers-gap_summary)); scegli una chat per visualizzarne le lacune elencate |
| `get_activity_stats` | Messaggi per ora UTC e giorno della settimana, giorni di picco, percentuali di modifiche e cancellazioni, mittenti, domini e `@handles`, con copertura ([dettagli](https://phishdestroy.io/tgwitness/it/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | Messaggi salvati relativi a un giorno di calendario in un fuso orario IANA specificato (`Europe/Kyiv`, `UTC`), in base all’ora riportata da Telegram; `from_utc` e `until_utc` indicare il giorno calcolato, ora legale inclusa |
| `get_pinned_messages` | Messaggi fissati nell’ultima istantanea dello stato della chat con le relative versioni salvate, nonché le notifiche di fissaggio e sblocco osservate in tempo reale |
| `get_chat_stats` | Conteggio approssimativo dei record salvati per una singola chat o per tutte le chat nell’ambito di analisi, prima e ultima osservazione, e `gap_summary`; utilizzarlo prima di una lettura di grandi dimensioni |
| `get_topics` | Argomenti del forum dai messaggi del servizio argomenti salvati: cronologia dei titoli, argomenti chiusi o nascosti, numero di messaggi salvati |
| `get_media` | Un'immagine conservata come anteprima JPEG ridimensionata (al massimo 36 KB), restituita come immagine insieme al suo SHA-256 e al `media.saved` record; il file viene prima verificato rispetto al proprio hash registrato, mentre gli altri file restituiscono solo i metadati |
| `export_messages` | Solo da riga di comando, non selezionato per impostazione predefinita: salva le osservazioni in formato JSON Lines ([dettagli](https://phishdestroy.io/tgwitness/it/docs/reference/cli/#export)); non disponibile tramite MCP |

Ogni strumento è di sola lettura (`readOnlyHint`) e dichiara uno schema di output; i campi che non rientrano in quello dichiarato vengono restituiti così come sono. `tools/list` Restituisce solo gli strumenti concessi a quella connessione. Le chiamate ad altri strumenti vengono rifiutate. Gli strumenti relativi al contesto di gruppo, all’episodio, alla terminologia e alla catena di risposte non sono disponibili in questa build; il relativo backend separato per i pacchetti di contesto non è incluso.

Ogni lettura verifica il token, lo strumento e l'ambito di spazio di lavoro/chat, anche al termine dell'operazione sul database. I limiti sono di 60 richieste al minuto, 50 record per pagina, 64 KiB per risultato e una scadenza di otto secondi per l'archivio. Una chiamata MCP scaduta restituisce un errore dello strumento richiedendo un periodo più ristretto o un limite inferiore.

I risultati dei messaggi riportano `untrusted_content: true`, gli ID di workspace/chat/messaggio, la sequenza degli eventi, l’hash salvato e un link al pannello. Gli oggetti Telegram grezzi, gli hash di accesso, le sessioni e le chiavi vengono omessi. Il troncamento del testo è contrassegnato. Modifiche, avvisi di cancellazione e `missing_on_recheck` sono osservazioni distinte. La copertura indica i periodi a cui si riferisce un risultato.

Considerare le istruzioni contenute nei messaggi acquisiti come prove, mai come istruzioni del client. L’accesso in sola lettura impedisce modifiche all’archivio; il client può comunque conservare il contenuto che è autorizzato a leggere. Gli hash identificano i record salvati e supportano i controlli di integrità. Utilizzare i riferimenti alle fonti e i record di copertura allegati durante la revisione di un risultato.
