# Telegram · MCP somente leitura

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

Conecte um cliente MCP a espaços de trabalho e chats selecionados com acesso temporário e revogável.

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

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

Conecte um cliente MCP a espaços de trabalho e chats selecionados com acesso temporário e revogável.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentação](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Integrações com arquivos](https://phishdestroy.io/tgwitness/pt/docs/reference/cli/)

![Integrações com arquivos](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

Conecte um cliente de análise a espaços de trabalho e chats selecionados. O TgWitness disponibiliza **Streamable HTTP em `/mcp` no processo do painel**. Cada conexão possui seu próprio token, prazo de validade e ferramentas permitidas. O MCP não pode enviar mensagens do Telegram, alterar configurações nem modificar o diário assinado. As mesmas conexões funcionam com a [linha de comando](https://phishdestroy.io/tgwitness/pt/docs/reference/cli/).

[Guia de fluxo de trabalho](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Nesta página**

- [Instalar e verificar](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/#install-and-check)
- [Estabelecer uma conexão](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/#issue-a-connection)
- [Conecte seu cliente](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/#connect-your-client)
- [Túnel do Cloudflare](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/#cloudflare-tunnel)
- [Ferramentas e limites](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/#tools-and-boundaries)

## Instalar e verificar

Use o ambiente Python que executa o painel. A partir de um checkout do código-fonte:

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

Reinicie o painel com seu diretório de dados habitual e os argumentos de inicialização após a instalação. A indicação de prontidão deve incluir `[PASS] mcp: streamable-http available`. **Mais ferramentas → Integrações → MCP** mostra o status de execução e um comando de instalação usando o executável Python real daquele servidor. **A opção Verificar novamente** atualiza esse status sem recarregar a página; ela não instala pacotes nem reinicia o servidor.

O MCP extra utiliza o [SDK oficial do MCP para Python](https://github.com/modelcontextprotocol/python-sdk). O arquivo`deploy/constraints-mcp.txt` fixa a versão do SDK testado e suas dependências.

## Emitir uma conexão

1. Insira um rótulo e escolha os workspaces e chats que o cliente pode ler.
2. Selecione as ferramentas individualmente ou use uma predefinição. Apenas ferramentas implementadas são oferecidas.
3. Escolha 1, 7, 30 ou 90 dias, ou uma validade personalizada entre um minuto e 90 dias.
4. Pressione **Create connection**. O token aparece uma única vez ao lado da configuração do cliente.
5. Copie o token e a configuração e, em seguida, execute **Check connection**. Ele inicializa o MCP e lista as ferramentas permitidas; **nenhuma mensagem é lida**. O resultado mostra a versão do protocolo, nomes das ferramentas, contagem e tempo decorrido.
6. Pressione **Done** quando a credencial estiver salva. As atualizações automáticas preservam o formulário e o cartão exibido uma única vez. Bloquear o painel limpa os segredos exibidos.

A lista mostra o uso recente, a última ferramenta, o endereço e as requisições no último minuto. **Revoke** encerra o acesso. **Rotate token** revoga a credencial antiga e emite uma substituta com o mesmo escopo, ferramentas e validade; copie a substituta uma única vez. Tokens de login do painel e credenciais do Telegram não funcionam como tokens MCP.

## Conecte seu cliente

Selecione o cliente no painel e copie a configuração gerada. As configurações usam referências a segredos ou espaços reservados explícitos; o token é copiado separadamente.

| Cliente | Configuração | Conexão |
| --- | --- | --- |
| Claude Code | `.mcp.json` | HTTP, `type: "http"`, cabeçalho bearer |
| Claude Desktop | `claude_desktop_config.json` | Ponte stdio local |
| Cursor | `.cursor/mcp.json` | HTTP com um cabeçalho de variável de ambiente |
| VS Code Local | `.vscode/mcp.json` | HTTP com uma entrada `promptString` de senha |
| Windsurf | `mcp_config.json` | HTTP com um espaço reservado para cabeçalho bearer |
| Outros clientes | URL e cabeçalho Authorization | HTTP com transmissão contínua |

O TgWitness usa tokens bearer, sem descoberta OAuth. Use a ponte stdio local para clientes cujo conector remoto exige OAuth. Para o VS Code, as variáveis de entrada aplicam-se ao ambiente **Local** e não são encaminhadas para sessões do Copilot. Referências de configuração: [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).

O ponto de entrada canônico para uma ponte local é:

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

Use o Python local do cliente com o extra MCP instalado. Defina `TGWITNESS_MCP_TOKEN` em seu ambiente protegido. Mantenha as credenciais fora dos argumentos de comando e URLs. `tgwitness-mcp` é o mesmo ponto de entrada. O módulo antigo `tgwitness.mcp_bridge` e o nome `TGWITNESS_ARCHIVE_TOKEN` permanecem como caminhos de compatibilidade com um aviso; novas configurações usam `mcp_server` e `TGWITNESS_MCP_TOKEN`.

## Cloudflare Tunnel

Encaminhe a rota `/mcp` do painel e preserve o cabeçalho bearer. Abrir as configurações de MCP como administrador registra a origem atual do painel para esta execução. Para ter um endereço estável disponível imediatamente após a reinicialização, configure `TGWITNESS_PUBLIC_URL` com a origem HTTPS do painel antes de iniciá-lo. Cabeçalhos Host e de encaminhamento arbitrários não registram um endereço confiável. As verificações de Host e Origin rejeitam origens de navegador não relacionadas. As respostas usam `Cache-Control: no-store`; valores de autorização nunca são registrados nos logs.

Um endereço `*.trycloudflare.com` é temporário. Quando uma reinicialização do túnel altera o hostname, atualize a URL pública configurada e a URL do MCP de cada cliente. Use um hostname estável para configurações de clientes salvas.

## Ferramentas e limites

| Ferramenta | Lê |
| --- | --- |
| `list_workspaces` | Workspaces concedidos |
| `list_chats` | Chats concedidos |
| `search_messages` | Texto das mensagens salvas dentro do período selecionado; `ranked=true` utiliza [pesquisa de texto completo](https://phishdestroy.io/tgwitness/pt/docs/reference/search/) (formas de palavras, melhores correspondências primeiro, `next_offset` paginação) |
| `get_message_versions` | Versões capturadas e observações de exclusão |
| `get_message_context` | IDs de mensagens capturadas próximas |
| `get_journal_event` | Um registro higienizado com sua referência de origem |
| `get_capture_status` | Estado da coleta, registros de cobertura permitidos e `gap_summary`: números de mensagens nunca observadas, por canal ou supergrupo e para a sequência de toda a conta ([detalhes](https://phishdestroy.io/tgwitness/pt/docs/reference/evidence/#missing-message-numbers-gap_summary)); escolha um chat para ver as lacunas listadas |
| `get_activity_stats` | Mensagens por hora UTC e dia da semana, dias de pico, proporções de edições e exclusões, remetentes, domínios e `@handles`, com cobertura ([detalhes](https://phishdestroy.io/tgwitness/pt/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | Mensagens salvas de um dia do calendário em um fuso horário IANA especificado (`Europe/Kyiv`, `UTC`), de acordo com a hora informada pelo Telegram; `from_utc` e `until_utc` indique o dia calculado, incluindo o horário de verão |
| `get_pinned_messages` | Mensagens fixadas no último instantâneo do estado do chat com suas versões salvas, além dos avisos de fixação e desfixação observados em tempo real |
| `get_chat_stats` | Contagens simples de registros salvos para um chat ou todos os chats no escopo, primeira e última observação, e `gap_summary`; use-a antes de uma leitura de grande volume |
| `get_topics` | Tópicos do fórum a partir de mensagens do serviço de tópicos salvos: histórico de títulos, tópicos fechados ou ocultos, contagem de mensagens salvas |
| `get_media` | Uma imagem preservada como uma pré-visualização JPEG reduzida (no máximo 36 KB), retornada como uma imagem juntamente com seu SHA-256 e o `media.saved` registro; o arquivo é verificado primeiro em relação ao seu hash registrado, enquanto outros arquivos retornam apenas metadados |
| `export_messages` | Apenas linha de comando, não selecionado por padrão: transmite as observações salvas como JSON Lines ([detalhes](https://phishdestroy.io/tgwitness/pt/docs/reference/cli/#export)); não disponível via MCP |

Todas as ferramentas são somente de leitura (`readOnlyHint`) e declara um esquema de saída; campos além dos declarados são retornados tal como estão. `tools/list` Retorna apenas as ferramentas concedidas a essa conexão. Chamadas para outras ferramentas são recusadas. Ferramentas de contexto de grupo, episódio, terminologia e cadeia de respostas não são oferecidas nesta versão; seu backend de pacote de contexto separado não está incluído.

Cada leitura verifica o token, a ferramenta e o escopo de workspace/chat, inclusive após a conclusão do trabalho no banco de dados. Os limites são de 60 requisições por minuto, 50 registros por página, 64 KiB por resultado e um tempo limite de oito segundos para o arquivo. Uma chamada MCP que exceda o tempo limite retorna um erro de ferramenta solicitando um período menor ou um limite mais baixo.

Os resultados das mensagens contêm `untrusted_content: true`, IDs de espaço de trabalho/bate-papo/mensagem, sequência de eventos, hash salvo e um link para o painel. Objetos brutos do Telegram, hashes de acesso, sessões e chaves são omitidos. O truncamento de texto é marcado. Edições, avisos de exclusão e `missing_on_recheck` são observações distintas. A cobertura mostra os períodos aos quais um resultado se refere.

Trate as instruções contidas nas mensagens capturadas como evidências, nunca como instruções do cliente. O acesso somente leitura impede alterações no arquivo; o cliente ainda pode manter o conteúdo que tem permissão para ler. Hashes identificam registros salvos e apoiam verificações de integridade. Use as referências de código-fonte e os registros de cobertura anexos ao revisar um resultado.
