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 · Русский
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
- 1. Instalação: Windows, Linux, macOS
- 2. Obtenha credenciais da API do Telegram
- 3. Configure o servidor local
- 4. Entre localmente
- 5. Conecte ao Codex
- 6. Leia o Telegram
- 7. Ative escritas
- Referência de configuração
- Privacidade e sessões
- Notificações
- Solução de problemas
- Atualizações e desenvolvimento
- Contribua e apoie
- Camada de privacidade planejada
- Uso avançado e licença
Recursos
| Recurso | Comportamento |
|---|---|
| Sete ferramentas de leitura | Diálogos, histórico, uma mensagem, pesquisa, não lidas, mais recentes e intervalos de tempo |
| Três ferramentas de escrita opcionais | Enviar texto simples, editar sua própria mensagem, excluir suas próprias mensagens |
| Controle de acesso | Listas de permissão separadas para leitura/escrita; lista de negação prevalece |
| Autorização local | Telefone, código e senha 2FA opcional inseridos no seu terminal |
| Sessão local | Criptografia DPAPI no Windows; arquivos somente do proprietário no Linux/macOS |
| Demonstração sem conta | Três chats fictícios e 12 mensagens; sem conexão com o Telegram |
| MCP padrão | stdio 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
- 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"
- 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
- 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
- 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
- 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.
- 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.
- Abra my.telegram.org e verifique o nome do host.
- Digite seu próprio número de telefone do Telegram no formato internacional, com
+e código do país. - 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.

Tela de login do site, sem número de telefone pessoal ou código de login.
- Abra API development tools. Se um aplicativo já existir, use seu
api_ideapi_hash; o Telegram atualmente permite um API ID por número de telefone. - Se você vir Create new application, preencha o formulário. Exemplo de detalhes:
| Campo do site | O que inserir |
|---|---|
| App title | Unofficial Telegram MCP, ou seu título descritivo. Os termos do Telegram exigem "Unofficial" antes de "Telegram" em títulos de aplicativos de terceiros. |
| Short name | Por exemplo, mytgmcplocal; use letras/dígitos latinos e siga as regras de comprimento e validação do site. |
| URL | Sua 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. |
| Platform | Desktop 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. |
| Description | Por exemplo, Personal local Telegram client via MTProto.. Descreva seu uso pretendido com sinceridade. |

Guia ilustrativo do formulário autenticado. Valores de exemplo; o site atual pode diferir.
- Selecione Create application. Copie App api_id e App api_hash para seu
.envlocal no passo 3.

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
- Telefone do Telegram (+código do país, oculto): digite seu número e pressione Enter.
- 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. - Se solicitado, senha 2FA do Telegram (oculta): digite sua senha do Telegram e pressione Enter.
- 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.
| Ferramenta | Parâmetros principais | Continuação |
|---|---|---|
list_dialogs | query?, limit=50 | cursor=next_cursor |
get_chat_history | chat_id, limit=50, before_id=0 | before_id=next_before_id |
get_message | chat_id, message_id | Uma mensagem ou null |
search_messages | query, chat_id?, limit=50 | cursor=next_cursor |
get_unread_messages | chat_id?, limit=50 | cursor=next_cursor |
get_latest_messages | chat_id?, limit=50, per_chat_limit=10 | cursor=next_cursor |
messages_between | chat_id, start, end, limit=50, before_id=0 | before_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_idatéhas_more=falsedentro 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 terhas_more=true;scan_limited=trueexplica 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.
limitpode mudar entre páginas. - Não lido significa mensagens recebidas acima da marca d'água de leitura atual do Telegram.
per_chat_limitlimita 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=truequando 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.
- Em modo somente leitura, use
list_dialogspara obter o ID numérico do chat desejado. Para uma primeira verificação, escolha Mensagens Salvas e use o ID retornado. - Edite o
.envlocal:
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.
- 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.
- 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.
| Ferramenta | Parâmetros | Restrições |
|---|---|---|
send_message | chat_id, text, reply_to_message_id?, silent=true | Texto simples literal, sem pré-visualização de link; o alvo de resposta deve existir no mesmo chat |
edit_message | chat_id, message_id, text | Apenas suas próprias mensagens de texto simples enviadas; legendas de mídia não são editáveis |
delete_messages | chat_id, message_ids, revoke=true | Apenas 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ável | Padrão | Finalidade |
|---|---|---|
TELEGRAM_API_ID | Vazio | Seu ID numérico de API; necessário para ao vivo/auth |
TELEGRAM_API_HASH | Vazio | Seu hash de API de 32 caracteres; necessário para ao vivo/auth |
TELEGRAM_SESSION_DIR | Específico do SO | Pasta 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_IDS | Vazio | IDs exatos negados para leitura e gravação; negação vence |
TELEGRAM_WRITE_ENABLED | false | Habilita ferramentas/capacidade de gravação |
TELEGRAM_WRITE_ALLOWED_CHAT_IDS | Vazio | Destinos de gravação permitidos exatos; vazio nega todos; sem curinga |
MCP_HTTP_TOKEN | Vazio | HTTP apenas: token ASCII aleatório separado, ≥32 caracteres, sem espaços em branco |
MCP_ALLOWED_HOSTS | 127.0.0.1:8765,localhost:8765 | Hosts permitidos HTTP, sem curinga |
MCP_ALLOWED_ORIGINS | http://127.0.0.1:8765,http://localhost:8765 | Origens 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:
| SO | Sessão padrão | Proteção |
|---|---|---|
| Windows | %LOCALAPPDATA%\TelegramReadOnlyMCP\session.dpapi | Criptografia 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.secret | Arquivo 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
| Problema | Verificação |
|---|---|
git/uv não reconhecidos | Reabra o terminal após a instalação; execute comandos de versão. |
| Credenciais ausentes | Nome e localização exatos de .env; valores próprios sem espaços reservados; --env-file absoluto correto. |
| Auth parece ignorar digitação | Entrada 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ário | Verifique credenciais/código novo e validação real do formulário localmente; aguarde se houver limite de taxa. |
| Sessão ausente/expirada | Mesmo usuário do SO/caminho de sessão; reexecute auth local após revogação. |
| Erro de permissão de armazenamento | Pasta local externa normal, sem symlinks/junctions; use protect-env, não permissões públicas. |
| Conexões duplicadas | Configure uma entrada standalone/plugin; pare instâncias obsoletas. |
| Sem ferramentas de gravação | Flag true, reinício do servidor, atualização da lista de ferramentas do cliente; verifique lista de permissões de ferramentas/plugin antigo. |
| Gravação negada | ID 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 rejeitada | Apenas suas mensagens enviadas; IDs corretos de chat/mensagem e permissões do Telegram. |
Página vazia, has_more=true | Continue com o cursor retornado; a página pode examinar chats sem correspondência. |
| FloodWait/limite de taxa | Aguarde os segundos informados; restrinja buscas repetidas a chats/datas selecionados. |
| Timeout de gravação/perda de conexão | O resultado pode ser desconhecido. Leia o destino antes de qualquer nova tentativa. |
| HTTP 401 | Token de portador correspondente servidor/cliente; stdio não precisa de nenhum. |
| Erro de Host/Origin HTTP | Host/origin explícito correspondente à porta real de loopback; sem curingas. |
| Codex não consegue iniciar processo | Caminhos absolutos de .venv Python e .env; uv sync --frozen após atualização. |
| Toast do ChatGPT contém texto do Telegram | Identifique 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ágio | Comportamento proposto |
|---|---|
| Isolar segredos | Excluir 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údo | Remover segredos de mensagem detectados/suspeitos usando regras determinísticas antes de NER/avaliação. Senhas coladas arbitrariamente podem permanecer não detectadas. |
| Minimizar e detectar | Cobrir 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 localmente | Ró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 opcional | Offline, 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 respostas | Cobrir 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ção | Candidato e fatos upstream | Por que avaliar |
|---|---|---|
| Detector local | Horizon-Labs/pii-redactor-small: 141M parâmetros, Apache-2.0, multilíngue | Menor candidato revisado com evidências publicadas em RU/EN; detecta intervalos. |
| Avaliador local opcional | Qwen/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 texto | Destinado a prototipagem/pesquisa; avaliação confiável de PII permanece não comprovada. |
| Comparação de detectores | openai/privacy-filter: Apache-2.0, 1.5B total / 50M parâmetros ativos, avaliações multilíngues | Detector 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.