Unofficial Telegram MCP

MCP MTProto local do Telegram para Codex: somente leitura por padrão, com escrita opcional de textos usando listas de permissão exatas de chats, e configuração em inglês/russo para Windows, Linux e macOS. Revise os termos da API/AI do Telegram antes de usar dados reais.

Documentação

Unofficial Telegram MCP

Inglês · Русский

CI Security checks Python 3.11+ MIT license

Configuração · Ferramentas de leitura · Escritas opcionais · Contribuir · Modelo de segurança

Um servidor local de Model Context Protocol com suporte para Codex e outros clientes MCP compatíveis. Suas ferramentas encontram diálogos do Telegram, pesquisam mensagens, leem histórico e mensagens não lidas e resumem um período escolhido via MTProto.

Antes de usar dados reais do Telegram: leia o guia de uso e licenciamento da plataforma e os Termos da API do Telegram. Compatibilidade técnica não estabelece permissão para processamento por IA; questões de uso da plataforma permanecem sem solução para este utilitário. Para um teste sem conta, use a demonstração fictícia abaixo.

Somente leitura por padrão. Opcionalmente, ative o envio de texto, edição das suas próprias mensagens e exclusão das suas próprias mensagens em chats explicitamente permitidos. Sem monitoramento em segundo plano ou envio de notificações de desktop.

Um projeto comunitário independente, não afiliado ao Telegram ou à OpenAI. Usa sua conta pessoal do Telegram, não um token do BotFather.

Conteúdo

Recursos

RecursoComportamento
Sete ferramentas de leituraDiálogos, histórico, uma mensagem, pesquisa, não lidas, mais recentes e intervalos de tempo
Três ferramentas de escrita opcionaisEnviar texto simples, editar sua própria mensagem, excluir suas próprias mensagens
Controle de acessoListas de permissão separadas para leitura/escrita; lista de negação prevalece
Autorização localTelefone, código e senha 2FA opcional inseridos no seu terminal
Sessão localCriptografia DPAPI no Windows; arquivos somente do proprietário no Linux/macOS
Demonstração sem contaTrês chats fictícios e 12 mensagens; sem conexão com o Telegram
MCP padrãostdio local e Streamable HTTP autenticado

Retorna texto/legendas de mensagens e metadados de anexos; não baixa mídia, entra em canais, acessa chats secretos ou fornece chamadas arbitrárias à API do Telegram. A leitura não marca mensagens como lidas. O modo de escrita adiciona apenas as três operações documentadas.

1. Instalação: Windows, Linux, macOS

Você precisa de uma conta existente no Telegram, acesso à Internet, Git, uv e Python 3.11 ou mais recente. Os comandos instalam Python 3.11 via uv e criam um .venv isolado; ativação é desnecessária.

Escolha um sistema operacional abaixo. Execute os comandos no terminal dele, uma linha por vez, sem copiar os acentos graves do Markdown. Os comandos de instalação baixam ferramentas de seus editores; veja o guia oficial de instalação do uv para alternativas.

Windows — PowerShell

  1. Abra Windows Terminal → PowerShell ou Windows PowerShell pelo menu Iniciar. Se necessário, instale Git e uv:
winget install --id Git.Git -e --source winget
winget install --id astral-sh.uv -e --source winget

Se o WinGet não estiver disponível, use o instalador do Git para Windows e o instalador oficial do uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. Feche e reabra o PowerShell para atualizar o PATH e execute:
git --version
uv --version
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Projects" | Out-Null
Set-Location "$env:USERPROFILE\Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
Set-Location .\telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if (-not (Test-Path -LiteralPath .env)) { Copy-Item -LiteralPath .env.example -Destination .env }
notepad .env

Você está em %USERPROFILE%\Projects\telegram-mcp. Mantenha o terminal aberto. Copie .env.example apenas para uma nova instalação; não sobrescreva um .env existente.

Linux — Terminal

  1. Abra um terminal. No Debian/Ubuntu, instale Git e curl se necessário:
sudo apt-get update
sudo apt-get install -y git curl

No Fedora, use sudo dnf install git curl; outras distribuições: use seu gerenciador de pacotes (guia de instalação do Git). Instale uv se necessário:

curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Feche e reabra o terminal e execute:
git --version
uv --version
mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
cd telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if [ ! -e .env ]; then cp .env.example .env; fi
nano .env

No nano: Ctrl+O → Enter para salvar, Ctrl+X para sair. Use seu editor preferido se o nano não estiver disponível. Você está em ~/Projects/telegram-mcp. Crie .env apenas uma vez; mantenha as configurações existentes durante atualizações.

macOS — Terminal

  1. Abra Applications → Utilities → Terminal. Se o Git não estiver disponível, instale as Command Line Tools da Apple e conclua o instalador na tela:
xcode-select --install

Instale uv se necessário:

curl -LsSf https://astral.sh/uv/install.sh | sh

Se você já usa Homebrew, brew install uv é outra opção.

  1. Feche e reabra o Terminal e execute:
git --version
uv --version
mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
cd telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if [ ! -e .env ]; then cp .env.example .env; fi
nano .env

No nano: Ctrl+O → Enter para salvar, Ctrl+X para sair. Você está em ~/Projects/telegram-mcp. Crie .env apenas uma vez; mantenha as configurações existentes durante atualizações.

Experimente a demonstração antes de conectar sua conta

A partir do diretório do repositório:

uv run --frozen telegram-mcp serve --demo

Este é um servidor stdio, então ele aguarda um cliente MCP; não é um terminal interativo do Telegram. Ctrl+C o interrompe. Na configuração do Codex do passo 5, acrescente --demo após serve para usar ferramentas fictícias. A demonstração não carrega sua sessão nem se conecta ao Telegram. Remova --demo para sua conta real. As datas são exemplos fixos, não mensagens atuais.

2. Obtenha credenciais da API do Telegram

Faça isso no seu navegador, não no PowerShell ou na conversa de IA. Veja o guia oficial de configuração de aplicativos do Telegram.

  1. Abra my.telegram.org e verifique o nome do host.
  2. Digite seu próprio número de telefone do Telegram no formato internacional, com + e código do país.
  3. Selecione Next, abra seu aplicativo oficial do Telegram e insira o código de login do site. Siga as instruções reais de entrega do Telegram.

Telegram developer website login screen

Tela de login do site, sem número de telefone pessoal ou código de login.

  1. Abra API development tools. Se um aplicativo já existir, use seu api_id e api_hash; o Telegram atualmente permite um API ID por número de telefone.
  2. Se você vir Create new application, preencha o formulário. Exemplo de detalhes:
Campo do siteO que inserir
App titleUnofficial Telegram MCP, ou seu título descritivo. Os termos do Telegram exigem "Unofficial" antes de "Telegram" em títulos de aplicativos de terceiros.
Short namePor exemplo, mytgmcplocal; use letras/dígitos latinos e siga as regras de comprimento e validação do site.
URLSua página pública real do aplicativo, se solicitado. A página de origem deste projeto é https://github.com/daniil-novel/telegram-mcp. Não é um callback OAuth. Deixe em branco se o formulário atual permitir.
PlatformDesktop se oferecido para um cliente local; caso contrário, Other com uma descrição. Isso não restringe o repositório a um único sistema operacional.
DescriptionPor exemplo, Personal local Telegram client via MTProto.. Descreva seu uso pretendido com sinceridade.

Illustrative application creation form with example values

Guia ilustrativo do formulário autenticado. Valores de exemplo; o site atual pode diferir.

  1. Selecione Create application. Copie App api_id e App api_hash para seu .env local no passo 3.

Illustrative location of API ID and API hash, with placeholders

Guia ilustrativo com espaços reservados, não credenciais reais. Não use valores de API de outra pessoa.

api_id é numérico; api_hash tem 32 caracteres hexadecimais. Estes não são seu número de telefone, código de login, senha 2FA, token de bot ou chave da OpenAI. Cada usuário obtém suas próprias credenciais; nenhuma é distribuída aqui.

Se a criação falhar, verifique os requisitos atuais do formulário e tente novamente mais tarde. Este projeto não pode contornar as restrições de conta do Telegram.

3. Configure o servidor local

Edite .env na raiz do repositório, ao lado de pyproject.toml. Use a janela do Notepad/nano aberta no passo 1. Substitua ambos os espaços reservados pelos seus próprios valores, sem < ou >:

TELEGRAM_API_ID=<YOUR_NUMERIC_API_ID>
TELEGRAM_API_HASH=<YOUR_32_CHARACTER_API_HASH>
TELEGRAM_SESSION_DIR=
TELEGRAM_ALLOWED_CHAT_IDS=*
TELEGRAM_DENIED_CHAT_IDS=
TELEGRAM_WRITE_ENABLED=false
TELEGRAM_WRITE_ALLOWED_CHAT_IDS=

Salve como .env, não .env.txt. Mantenha as configurações HTTP de .env.example inalteradas para stdio. Um diretório de sessão vazio usa o padrão do sistema operacional.

TELEGRAM_ALLOWED_CHAT_IDS=* permite ler todos os diálogos na nuvem acessíveis à sua conta. Após list_dialogs, você pode substituí-lo por IDs numéricos exatos. Uma lista de permissão de leitura vazia nega todos os chats. As escritas permanecem desativadas até o passo 7.

No mesmo terminal no repositório, restrinja as permissões de .env:

uv run --frozen telegram-mcp protect-env

Nunca cole API hash, telefone, código de login, senha 2FA, .env ou arquivos de sessão em chats, issues ou capturas de tela. .env é ignorado pelo Git; isso não protege uploads manuais.

4. Entre localmente

Execute isso você mesmo em um PowerShell/Terminal interativo, ainda no repositório:

uv run --frozen telegram-mcp auth
  1. Telefone do Telegram (+código do país, oculto): digite seu número e pressione Enter.
  2. Código de login do Telegram (oculto): digite o novo código enviado pelo Telegram e pressione Enter. Este login é separado de my.telegram.org.
  3. Se solicitado, senha 2FA do Telegram (oculta): digite sua senha do Telegram e pressione Enter.
  4. Aguarde Authorized. Session stored locally; no messages were read or changed.

A entrada oculta não mostra nenhum caractere ou asterisco enquanto você digita. Isso é esperado. A sessão protegida permite que inícios posteriores funcionem sem outro código. Códigos e senhas 2FA não são salvos. A autorização é um comando local separado; não há ferramenta de login MCP.

Inspecione/revogue o acesso em Telegram → Configurações → Dispositivos. A sessão usa o nome do dispositivo do projeto. Uma vez encerrada, o servidor não pode entrar novamente sozinho.

5. Conecte ao Codex

Recomendado: stdio local. O Codex inicia o servidor; nenhum endpoint público ou token HTTP é necessário.

Abra a configuração do usuário do Codex, geralmente %USERPROFILE%\.codex\config.toml no Windows ou ~/.codex/config.toml no Linux/macOS. Crie se necessário. Acrescente uma tabela, preservando as configurações existentes. Substitua todos os caminhos de exemplo pelos seus próprios caminhos absolutos. Aspas simples do TOML mantêm as barras invertidas do Windows literais.

Configuração do Windows

[mcp_servers.telegram]
command = 'C:\Users\YOUR_USERNAME\Projects\telegram-mcp\.venv\Scripts\python.exe'
args = ['-m', 'telegram_readonly_mcp', '--env-file', 'C:\Users\YOUR_USERNAME\Projects\telegram-mcp\.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

Configuração do Linux

[mcp_servers.telegram]
command = '/home/YOUR_USERNAME/Projects/telegram-mcp/.venv/bin/python'
args = ['-m', 'telegram_readonly_mcp', '--env-file', '/home/YOUR_USERNAME/Projects/telegram-mcp/.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

Configuração do macOS

[mcp_servers.telegram]
command = '/Users/YOUR_USERNAME/Projects/telegram-mcp/.venv/bin/python'
args = ['-m', 'telegram_readonly_mcp', '--env-file', '/Users/YOUR_USERNAME/Projects/telegram-mcp/.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

O módulo de compatibilidade telegram_readonly_mcp permanece inalterado, inclusive no modo de escrita. Não o renomeie em args. Exemplos de configuração também estão disponíveis.

Reinicie/recarregue a conexão MCP, ou reinicie o Codex e abra um novo chat se a lista de ferramentas estiver em cache. No Codex CLI, codex mcp list lista os servidores configurados e /mcp mostra as conexões. Veja a documentação oficial do MCP do Codex. O .codex/config.toml de um projeto confiável pode ser usado para configuração no escopo do projeto.

O caminho explícito do Python evita depender do uv estar no PATH do aplicativo de desktop. --env-file é explícito porque o Codex pode iniciar o processo de outro diretório.

Usuários existentes de plugins: use o plugin do projeto ou esta entrada independente. Desative duplicatas. Um plugin pode incluir seu próprio runtime; atualizar um clone sozinho não atualiza o plugin instalado.

Primeira solicitação:

Use o Telegram MCP para listar meus diálogos. Mostre títulos e IDs numéricos dos chats. Não envie, edite ou exclua nada.

Você deve ver os diálogos reais permitidos. Se source=demo, remova --demo da configuração.

6. Leia o Telegram

Descreva a tarefa em linguagem natural, nomeando o chat e o período:

Encontre "Project Alpha" e resuma as mensagens de 1º de outubro a 3 de outubro de 2026 em UTC+03:00. Siga todas as páginas nesse período e inclua IDs de chats e IDs de mensagens para as fontes.

Pesquise nesse chat por "deadline" e mostre as mensagens correspondentes com datas.

Mostre mensagens não lidas do meu chat de trabalho sem marcá-las como lidas.

Ferramentas de leitura

Todas as ferramentas aceitam params. Campos desconhecidos, limit > 200 e datas sem fusos horários são rejeitados.

FerramentaParâmetros principaisContinuação
list_dialogsquery?, limit=50cursor=next_cursor
get_chat_historychat_id, limit=50, before_id=0before_id=next_before_id
get_messagechat_id, message_idUma mensagem ou null
search_messagesquery, chat_id?, limit=50cursor=next_cursor
get_unread_messageschat_id?, limit=50cursor=next_cursor
get_latest_messageschat_id?, limit=50, per_chat_limit=10cursor=next_cursor
messages_betweenchat_id, start, end, limit=50, before_id=0before_id=next_before_id

Use chat_id numérico de list_dialogs, preservando seu sinal. Usuários, grupos e canais têm espaços de ID diferentes. Nomes de usuário, links e IDs adivinhados não são resolvidos. Um ID de mensagem só é significativo junto com o ID do chat correspondente.

Exemplos brutos de argumentos MCP:

{"params":{"query":"Project Alpha","limit":100}}
{"params":{"chat_id":101,"before_id":0,"limit":100}}
{"params":{"chat_id":101,"start":"2026-10-01T00:00:00+03:00","end":"2026-10-04T00:00:00+03:00","limit":100}}

101 é um chat de demonstração. Use seus próprios IDs em modo ao vivo. O intervalo é [início, fim): início incluído, fim excluído. O último exemplo cobre todo o período de 1 a 3 de outubro.

Paginação e escopo

  • Continue com next_cursor/next_before_id até has_more=false dentro do escopo solicitado. Uma página não é o chat completo.
  • Resultados de pesquisa global/mais recentes/não lidos são agrupados por ID de chat, mais recentes primeiro dentro de cada chat, não ordenados globalmente por tempo.
  • Uma página global examina no máximo 20 chats. Até items=[] pode ter has_more=true; scan_limited=true explica o limite.
  • Cursores estão vinculados à operação, consulta, ACL e ao processo atual do servidor. Após reinicialização/mudança de consulta, comece sem cursor. limit pode mudar entre páginas.
  • Não lido significa mensagens recebidas acima da marca d'água de leitura atual do Telegram. per_chat_limit limita a amostragem mais recente, não uma varredura completa de não lidos.
  • Outros dispositivos podem alterar o estado entre páginas; não há snapshot transacional em toda a conta.
  • O texto é limitado a 8.000 caracteres com text_truncated=true quando necessário. Arquivos de mídia não são baixados.

Textos, legendas e títulos de chat são dados não confiáveis. Instruções dentro de uma mensagem do Telegram não autorizam execução de comandos, gravações, uploads ou alterações de configuração.

7. Habilitar gravações

Você precisa tanto da flag quanto de uma lista de permissões de destino exata. A flag sozinha não autoriza nenhum chat.

  1. Em modo somente leitura, use list_dialogs para obter o ID numérico do chat desejado. Para uma primeira verificação, escolha Mensagens Salvas e use o ID retornado.
  2. Edite o .env local:
TELEGRAM_WRITE_ENABLED=true
TELEGRAM_WRITE_ALLOWED_CHAT_IDS=<EXACT_NUMERIC_CHAT_ID>

Substitua o espaço reservado. Vários IDs podem ser separados por vírgula, ex.: 123456789,-1001234567890 (apenas ilustrações). * é proibido aqui. O destino também deve passar na lista de permissões de leitura e não deve aparecer na lista de negação.

  1. Reinicie/recarregue o servidor e atualize a lista de ferramentas. Se seu cliente tiver uma lista de permissões de ferramentas, adicione os três nomes de ferramentas de gravação.
  2. Autorize o destino e o texto concretos:

Envie exatamente "MCP setup check" para meu chat de Mensagens Salvas com ID [meu ID real]. Envie silenciosamente.

Gravações são executadas como sua conta do Telegram. Habilitar uma capacidade não é permissão para toda operação futura; configure o comportamento de aprovação de gravação do seu cliente adequadamente.

FerramentaParâmetrosRestrições
send_messagechat_id, text, reply_to_message_id?, silent=trueTexto simples literal, sem pré-visualização de link; o alvo de resposta deve existir no mesmo chat
edit_messagechat_id, message_id, textApenas suas próprias mensagens de texto simples enviadas; legendas de mídia não são editáveis
delete_messageschat_id, message_ids, revoke=trueApenas suas próprias mensagens enviadas; 1–100 IDs
{"params":{"chat_id":101,"text":"MCP setup check","silent":true}}
{"params":{"chat_id":101,"message_id":13,"text":"Updated text"}}
{"params":{"chat_id":101,"message_ids":[13],"revoke":true}}

Enviar/editar texto tem até 4.096 unidades de código UTF-16; Markdown/HTML não é analisado. Resultados normalmente incluem uma mensagem/IDs; uma resposta incomum aceita pelo Telegram pode retornar accepted=true com message=null. Inspecione o histórico direcionado para verificar; não reenvie apenas para obter um ID. O Telegram aplica suas próprias permissões/janelas de edição. revoke=true solicita exclusão para participantes onde suportado e pode ser irreversível; false solicita exclusão do seu lado onde disponível. Canais e megagrupos exigem revoke=true; este servidor rejeita revoke=false para esses destinos.

Não repita automaticamente uma gravação após timeout ou resposta incerta. Ela pode já ter sido bem-sucedida. Inspecione o destino/histórico antes de decidir tentar novamente.

Para desabilitar gravações, defina TELEGRAM_WRITE_ENABLED=false e reinicie. As ferramentas de gravação desaparecem e o guarda de RPC rejeita gravações. Entrar/sair, reações, encaminhamento, uploads de mídia, alterações de perfil, recibos de leitura e RPCs arbitrários permanecem indisponíveis.

Referência de configuração

.env é carregado do diretório atual do processo, a menos que --env-file esteja antes do subcomando. Sem busca ascendente. Variáveis de ambiente do processo substituem .env. Reinicie para aplicar alterações.

uv run --frozen telegram-mcp --env-file /absolute/path/to/.env protect-env
uv run --frozen telegram-mcp --env-file /absolute/path/to/.env auth
uv run --frozen telegram-mcp --env-file /absolute/path/to/.env serve

No Windows, use um caminho Windows entre aspas.

VariávelPadrãoFinalidade
TELEGRAM_API_IDVazioSeu ID numérico de API; necessário para ao vivo/auth
TELEGRAM_API_HASHVazioSeu hash de API de 32 caracteres; necessário para ao vivo/auth
TELEGRAM_SESSION_DIREspecífico do SOPasta de sessão externa; em branco usa o padrão
TELEGRAM_ALLOWED_CHAT_IDS*Ler todos os diálogos acessíveis, IDs exatos separados por vírgula, ou vazio para nenhum
TELEGRAM_DENIED_CHAT_IDSVazioIDs exatos negados para leitura e gravação; negação vence
TELEGRAM_WRITE_ENABLEDfalseHabilita ferramentas/capacidade de gravação
TELEGRAM_WRITE_ALLOWED_CHAT_IDSVazioDestinos de gravação permitidos exatos; vazio nega todos; sem curinga
MCP_HTTP_TOKENVazioHTTP apenas: token ASCII aleatório separado, ≥32 caracteres, sem espaços em branco
MCP_ALLOWED_HOSTS127.0.0.1:8765,localhost:8765Hosts permitidos HTTP, sem curinga
MCP_ALLOWED_ORIGINShttp://127.0.0.1:8765,http://localhost:8765Origens permitidas HTTP, sem curinga

Privacidade e sessões

O servidor roda localmente e contata o Telegram para operações solicitadas. Ele não contém cliente de API OpenAI e não envia mensagens diretamente a um modelo. Respostas MCP são visíveis ao cliente conectado e seu modelo. Limite chats e escopo a material que você está autorizado a compartilhar.

Caminhos de armazenamento são preservados da versão anterior:

SOSessão padrãoProteção
Windows%LOCALAPPDATA%\TelegramReadOnlyMCP\session.dpapiCriptografia DPAPI do usuário atual e ACL restrita
Linux/macOS$XDG_DATA_HOME/telegram-readonly-mcp/session.secret, padrão ~/.local/share/telegram-readonly-mcp/session.secretArquivo 0600, pasta 0700, verificações de proprietário; não criptografado em repouso

Auth e servidor devem rodar sob o mesmo usuário do SO. Armazenamento personalizado deve estar fora do repositório; symlinks/junctions são rejeitados. Nenhum banco de dados de mensagens/contatos é criado. Arquivos de sessão concedem acesso à conta; não os envie ou transfira.

O Telegram não tem escopo de sessão de usuário somente leitura. Este código restringe ferramentas, verifica ACLs e protege classes exatas de RPC MTProto, incluindo solicitações aninhadas. Operações desconhecidas falham de forma segura. Anotações de ferramentas são dicas; o código aplica a restrição. Auth é separado e não pode enviar/editar/excluir mensagens.

ACL filtra saída MCP e solicitações de histórico direcionadas. A listagem de diálogos do Telegram pode colocar metadados/últimas mensagens de chats negados na memória do backend; eles são excluídos da saída. Use uma conta separada para isolamento de metadados mais estrito.

Revise os Termos da API do Telegram e os Termos de Licenciamento de Conteúdo e Raspagem de IA. Os termos da API restringem amplamente o uso de dados da plataforma para desenvolvimento, aprimoramento ou implantação de IA. Compatibilidade técnica MCP não é uma afirmação de que o Telegram autoriza um uso específico de IA. MIT licencia este código, não conteúdo do Telegram ou exceções aos termos da plataforma.

Leia o modelo de segurança e seus limites: regras do repositório, Bandit, varreduras de dependências/segredos e CodeQL. SECURITY.md cobre relatórios privados de vulnerabilidades e revogação. Verificações reduzem riscos conhecidos; conteúdo permitido permanece visível ao cliente/modelo, e injeção de prompt não é totalmente resolvida.

Notificações

Este servidor não assina atualizações de mensagens em segundo plano, não inicia monitoramento, não registra dispositivos push nem emite notificações de toast na área de trabalho. Leituras não enviam recibos de leitura. Envios opcionais usam o silent=true do Telegram por padrão: ele suprime o som de notificação onde suportado, não necessariamente banners do destinatário.

Um toast rotulado como ChatGPT não é suficiente para identificar qual integração o produziu. Este servidor Python não tem função de notificação de área de trabalho; o cliente proprietário, uma aba do navegador ou outra integração pode produzir o toast.

Se você usa Telegram Web, abra o site real do Telegram Web no mesmo navegador que o hospeda, depois use o ícone à esquerda do endereço → Configurações do site / Permissões → Notificações → Bloquear. Isso bloqueia apenas as notificações desse site. Veja as instruções oficiais de permissão do Chrome e Edge. Para um navegador no aplicativo, use seus controles de permissão por site, se fornecidos; caso contrário, feche a aba do Telegram Web e identifique a fonte da notificação antes de alterar configurações mais amplas. Se um monitor agendado do Telegram for responsável, desative esse monitor específico em seu cliente proprietário. Uma alteração no código do servidor não pode revogar a permissão de notificação independente de um navegador.

Solução de problemas

ProblemaVerificação
git/uv não reconhecidosReabra o terminal após a instalação; execute comandos de versão.
Credenciais ausentesNome e localização exatos de .env; valores próprios sem espaços reservados; --env-file absoluto correto.
Auth parece ignorar digitaçãoEntrada oculta não mostra nada. Digite e pressione Enter.
"Use um terminal interativo"Execute auth você mesmo no PowerShell/Terminal, fora de uma ferramenta MCP.
Telegram rejeita auth/formulárioVerifique credenciais/código novo e validação real do formulário localmente; aguarde se houver limite de taxa.
Sessão ausente/expiradaMesmo usuário do SO/caminho de sessão; reexecute auth local após revogação.
Erro de permissão de armazenamentoPasta local externa normal, sem symlinks/junctions; use protect-env, não permissões públicas.
Conexões duplicadasConfigure uma entrada standalone/plugin; pare instâncias obsoletas.
Sem ferramentas de gravaçãoFlag true, reinício do servidor, atualização da lista de ferramentas do cliente; verifique lista de permissões de ferramentas/plugin antigo.
Gravação negadaID assinado exato, lista de permissões de gravação e regras de leitura permitir/negar. Lista de gravação vazia não permite nenhuma.
Edição/exclusão rejeitadaApenas suas mensagens enviadas; IDs corretos de chat/mensagem e permissões do Telegram.
Página vazia, has_more=trueContinue com o cursor retornado; a página pode examinar chats sem correspondência.
FloodWait/limite de taxaAguarde os segundos informados; restrinja buscas repetidas a chats/datas selecionados.
Timeout de gravação/perda de conexãoO resultado pode ser desconhecido. Leia o destino antes de qualquer nova tentativa.
HTTP 401Token de portador correspondente servidor/cliente; stdio não precisa de nenhum.
Erro de Host/Origin HTTPHost/origin explícito correspondente à porta real de loopback; sem curingas.
Codex não consegue iniciar processoCaminhos absolutos de .venv Python e .env; uv sync --frozen após atualização.
Toast do ChatGPT contém texto do TelegramIdentifique o navegador/integração produtor; bloqueie a permissão de notificação do site do Telegram Web em seu próprio navegador ou desative o monitor específico. Veja Notificações; a captura de tela sozinha não prova a fonte.

Para ajuda, abra uma issue no GitHub com SO, versões de Python/uv, comando e erro editado. Exclua segredos e conteúdos privados de chat.

Atualizações e desenvolvimento

No repositório:

git pull --ff-only
uv sync --frozen

Reinicie a conexão. Preserve .env e sessões externas. Não sobrescreva .env com o exemplo. A CLI legada telegram-readonly-mcp e o módulo telegram_readonly_mcp são mantidos.

Verificações de desenvolvimento sem conta:

uv sync --frozen --extra dev
uv run --frozen --extra dev python -m pytest -q
uv run --frozen --extra dev ruff check .
uv run --frozen --extra dev ruff format --check .
uv build

Os testes usam respostas sintéticas/falsas; passar nos testes não estabelece testes ao vivo de cada conta/OS/ambiente Docker do Telegram. Evidências/limites registrados: VALIDATION.md. Contribuições: CONTRIBUTING.md. Alterações: CHANGELOG.md.

Contribua e apoie

Relatórios de bugs, correções de documentação e melhorias focadas são bem-vindos em inglês ou russo. Fork → branch de feature → pull request para main; veja CONTRIBUTING.md para comandos exatos e verificações sem conta. Um fork público não lhe dá acesso de escrita a este repositório. Reporte vulnerabilidades por meio de SECURITY.md, usando exemplos sintéticos.

Se este projeto for útil para você, dê uma ⭐ estrela no GitHub. Isso ajuda outras pessoas a descobrirem a ferramenta.

Camada de privacidade planejada

Planejada, não implementada. Pesquisa verificada em 2026-10-06. Esta versão retorna dados permitidos do Telegram sem anonimização automática. Nenhum sinalizador de privacidade existe ainda. Esta pesquisa usou documentação pública, sem downloads de modelos, inferência ou conversas privadas.

Substitua informações identificáveis localmente antes de uma resposta MCP chegar a um modelo em nuvem. Pseudônimos preservam significado; criptografia protege arquivos armazenados. Texto de mensagem criptografado não pode suportar análise semântica comum. O contexto ainda pode identificar pessoas após a pseudonimização; meça o risco de divulgação usando orientações como NIST SP 800-188.

Um proxy de transporte opcional do Telegram altera o roteamento de rede; ele não remove dados pessoais das respostas MCP.

Pipeline local proposto

Nossa recomendação: comece com um piloto somente leitura; adicione resolução de alias segura para escrita somente após os testes de aceitação passarem. Estes são requisitos propostos.

EstágioComportamento proposto
Isolar segredosExcluir credenciais de aplicativo, sessões, códigos de login e 2FA de todos os modelos. Visar arquivos criptografados com AEAD usando chaves do keystore do SO em todas as plataformas; texto simples permanece necessário na memória do processo.
Escanear conteúdoRemover segredos de mensagem detectados/suspeitos usando regras determinísticas antes de NER/avaliação. Senhas coladas arbitrariamente podem permanecer não detectadas.
Minimizar e detectarCobrir texto, legendas, títulos, nomes, nomes de usuário, links, IDs e metadados de resposta/encaminhamento. Omitir campos desnecessários. Usar blocos limitados sobrepostos e validar rigorosamente os intervalos.
Substituir localmenteRótulos legíveis com escopo de tarefa vinculados a identificadores locais aleatórios e impossíveis de adivinhar; mapeamento criptografado e expirante. Manter IDs originais localmente. Hashes globais permitem correlação entre tarefas.
Avaliador opcionalOffline, sem ferramentas/rede; apenas consultivo, não pode substituir bloqueios. Timeout de estágio obrigatório, OOM, saída malformada ou entrada não suportada bloqueiam a exportação.
Controlar respostasCobrir cada ferramenta de leitura, página e erro. Sem pré-visualizações brutas ou conteúdo sensível em logs/diagnósticos.

Depois, restaure aliases em um visualizador local e, após aprovação exata, imediatamente antes da operação do Telegram: a aprovação humana de escrita deve vincular texto restaurado exato, destino e ação, preservando ACLs. Nunca exponha texto simples restaurado por meio de resultados MCP, pré-visualizações, _meta, logs ou erros.

A cobertura termina nas novas saídas deste servidor. Dados enviados anteriormente à nuvem, prompts/histórico de clientes privados e outros conectores exigem controles separados.

Modelos a avaliar

Piloto recomendado em russo + inglês: regras determinísticas mais Horizon, opcionalmente um avaliador local Qwen. A seleção é limitada a candidatos revisados.

FunçãoCandidato e fatos upstreamPor que avaliar
Detector localHorizon-Labs/pii-redactor-small: 141M parâmetros, Apache-2.0, multilíngueMenor candidato revisado com evidências publicadas em RU/EN; detecta intervalos.
Avaliador local opcionalQwen/Qwen3.5-0.8B: 0.8B parâmetros de modelo de linguagem, Apache-2.0; o card afirma 201 idiomas/dialetos, documenta serviço somente textoDestinado a prototipagem/pesquisa; avaliação confiável de PII permanece não comprovada.
Comparação de detectoresopenai/privacy-filter: Apache-2.0, 1.5B total / 50M parâmetros ativos, avaliações multilínguesDetector de intervalos dedicado com pesos residentes muito maiores.

Horizon relata 0,75 de recall de redação em nível de caractere em um conjunto de dados externo em russo: insuficiente sozinho. Pontuações publicadas usam conjuntos de dados/definições diferentes e não podem estabelecer uma classificação universal. Recall específico do Telegram e requisitos de recursos permanecem não medidos.

Dependências futuras incluem Transformers/PyTorch ou ONNX e um mecanismo de avaliador local. Exija revisões fixadas e revisadas e hashes SHA-256 de pesos, inferência offline e sem fallback automático para nuvem, inclusive em erros de modelo.

OpenRouter: pesquisa suplementar apenas

Sensitive Info usa regex/Presidio, mas prossegue em timeout de NLP; o OpenRouter já recebe a entrada. Custom Classifiers são executados após a conclusão. Nenhum fornece nossa fronteira local de pré-saída. ZDR limita a retenção; provedores ainda processam texto simples.

O catálogo ao vivo listou google/gemma-3-4b-it no corte; Qwen3-0.6B/1.7B estavam ausentes apesar das páginas de marketing. Avalie Gemma apenas em exemplos sintéticos/já sanitizados. Um avaliador em nuvem nunca deve receber conversas brutas para decidir sua segurança de exportação.

Portões de aceitação antes do envio da implementação

  • Meça recall de intervalos sensíveis em RU/EN, risco residual de identificação e utilidade de resumo em fixtures sintéticas do Telegram, incluindo flexão, scripts mistos, segredos e pistas contextuais.
  • Verifique todos os campos/sete ferramentas, páginas, deslocamentos Unicode e expiração. Exija zero marcadores críticos de vazamento observados em testes sintéticos de saída/log/erro; isole estruturalmente segredos de aplicativo.
  • Teste injeção, timeout, OOM, saídas malformadas e rede negada; preserve ACLs e autorização humana, com cada falha de processamento bloqueando a exportação.
  • Meça CPU/RAM e efeitos de quantização; revise dependências, hashes de modelos e ciclo de vida do mapa criptografado. Publique limitações: pseudonimização não pode garantir anonimato.

Uso avançado e licença

Veja orientação avançada de HTTP/Docker/navegador. Comece com stdio local.

Licença MIT, copyright 2026 daniil-novel. Retenha avisos de copyright e permissão em cópias ou porções substanciais. Crédito visível ao autor é bem-vindo como cortesia; o MIT não o exige nem torna um aplicativo inteiro incorporador licenciado sob MIT. Atribuição prática e limites de plataforma: guia de licenciamento. Dependências mantêm suas próprias licenças: avisos de terceiros.

Nomes/marcas do Telegram e arte do site mantêm os direitos de seus proprietários. O logotipo oficial do Telegram não é o logotipo deste aplicativo.