better-telegram-mcp

Better Telegram MCP

mcp-name: io.github.n24q02m/better-telegram-mcp

Telegram para agentes de IA — mensagens, chats, mídia e contatos nos modos bot e conta de usuário completa.

Projetos irmãos de n24q02m (clique para expandir)

Projeto	Slogan	Tag
agent-chat-plugin	Agentes de IA conversam entre si em uma pasta compartilhada — sem retransmissão humana, sem orquestrador, tra...	Ferramentas
better-code-review-graph	Grafo de conhecimento para revisões de código eficientes em tokens — busca semântica e chamada...	MCP
better-drive	Sincronização bidirecional com Google Drive com filtro .driveignore — mecanismo rclone, bandeja do Windows	Ferramentas
better-email-mcp	E-mail IMAP/SMTP para agentes de IA — ler, enviar, organizar pastas e gerenciar anex...	MCP
better-godot-mcp	Servidor MCP composto para Godot Engine — 17 ferramentas compostas para desenvolvimento de jogos assistido por IA...	MCP
better-notion-mcp	Notion com foco em Markdown para agentes de IA — páginas, bancos de dados, blocos e comentários...	MCP
better-semantic-release	Fork drop-in do python-semantic-release com proteções de segurança de release integradas (orp...	Ferramentas
better-telegram-mcp	Telegram para agentes de IA — mensagens, chats, mídia e contatos nos modos bot e conta de usuário completa...	MCP
better-workspace-mcp	Servidor MCP do Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Marketplace de plugins do Claude Code para os servidores MCP n24q02m — instale busca web...	Marketplace
imagine-mcp	Compreensão e geração de imagem e vídeo para agentes de IA — em Gemini, Op...	MCP
jules-task-archiver	Extensão do Chrome para operações em lote em tarefas do Jules via API batchexecute — a...	Ferramentas
mcp-core	Fundação compartilhada para construir servidores MCP — transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memória de IA persistente com busca híbrida e sincronização incorporada. Aberto, gratuito, ilimit...	MCP
qwen3-embed	Embedding e re-ranking de texto Qwen3 leve via ONNX Runtime e GGUF	Biblioteca
skret	Segredos sem o servidor.	CLI
tacet	Cascata neuro-simbólica autodestilante que amortiza o custo de LLM em conhecimento...	Ferramentas
web-core	Pacote de infraestrutura web compartilhado para busca, raspagem, segurança HTTP e st...	Biblioteca
wet-mcp	Servidor MCP de código aberto para agentes de IA: busca web, extração de conteúdo e lib...	MCP

Sumário

• Recursos
• Status
• Instalação
• Smithery
• Configuração
• CLI
• Documentação
• Ferramentas
• Comparação
• Segurança
• Compilar a partir do código-fonte
• Implantar no Cloudflare
• Modelo de confiança
• Licença

Recursos

• Modo duplo — API de Bot (httpx) para bots, MTProto (Telethon) para contas de usuário
• 7 ferramentas com despacho de ações: message, chat, media, contact, config, help, config__open_relay
• Detecção automática de modo — Defina o token do bot para o modo bot, ou credenciais de API para o modo usuário
• Autenticação OTP baseada na web — Formulário de retransmissão em modo HTTP no navegador lida com telefone, OTP e 2FA para contas de usuário
• Autenticação CLI local — auth configura uma máquina de usuário único; login permanece como um alias obsoleto
• Anotações de ferramentas — Cada ferramenta declara readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• Recursos MCP — Documentação disponível como recursos telegram://docs/*
• Segurança reforçada — Proteção SSRF, prevenção de travessia de caminho, sanitização de erros

Status

Dois transportes limpos: stdio (padrão, modo local de usuário único) e HTTP (modo bot + usuário, configuração de retransmissão no navegador, multi-usuário opcional). Sem camada de ponte daemon e sem auto-inicialização a partir do stdio. Consulte a Visão geral dos modos para o modelo completo de transporte.

Servidores MCP irmãos do mesmo autor estão listados na seção recolhível acima — eles compartilham esta arquitetura, então os padrões de instalação são transferíveis.

Instalação

# Method 1 (default): plugin install via Claude Code (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Method 1 (CLI): direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcp

# Method 2 (fallback): Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp

# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP
docker run -d --name better-telegram-mcp-http -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PUBLIC_URL=https://telegram.example.com \
  -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \
  n24q02m/better-telegram-mcp:latest

O modo stdio é o modo local de usuário único. O modo bot usa TELEGRAM_BOT_TOKEN; o modo usuário pode ser configurado localmente com better-telegram-mcp auth --phone <+number>. O modo usuário HTTP usa o formulário de retransmissão baseado no navegador em /authorize para telefone, OTP e 2FA.

Endpoint remoto — uma implantação HTTP é protegida por OAuth e serve /mcp. Aponte qualquer cliente MCP que fale Streamable HTTP + OAuth 2.1 para https://<your-host>/mcp; cada usuário completa a configuração de retransmissão no navegador (token do bot, ou telefone + OTP) na primeira conexão. Para executar um, use o método HTTP Docker acima ou a implantação no Cloudflare abaixo.

Matrizes de configuração completas estão no site de documentação canônico mcp.n24q02m.com/servers/better-telegram-mcp/setup/, e os trechos de colar-no-agente em claude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.

Smithery

Também listado no Smithery. Conforme smithery.yaml, o Smithery inicia o servidor via stdio com uvx --python 3.13 better-telegram-mcp e não aceita configuração no momento da instalação (configSchema vazio) — as credenciais são fornecidas em tempo de execução pelo próprio fluxo de configuração do servidor: a variável de ambiente TELEGRAM_BOT_TOKEN ou o comando local auth para o modo stdio de usuário único, ou o formulário de retransmissão no navegador para o modo usuário HTTP (consulte Configuração).

Configuração

As configurações são carregadas de variáveis de ambiente com prefixo TELEGRAM_ (Pydantic Settings).

Modo stdio (local, usuário único):

Variável	Obrigatória	Descrição
TELEGRAM_BOT_TOKEN	Sim	Token do bot do @BotFather (formato 123456789:ABCdef...)

Modo HTTP (bot + usuário): as credenciais são inseridas pelo formulário de retransmissão no navegador, não por variáveis de ambiente. Variáveis de ambiente do lado do servidor para auto-hospedagem:

Variável	Obrigatória	Padrão	Descrição
MCP_TRANSPORT	Sim	stdio	Defina como http para habilitar o modo HTTP (flag --http da CLI ou TRANSPORT_MODE=http também funcionam)
PUBLIC_URL	Auto-hospedagem	--	URL pública do servidor; a presença habilita o ramo OAuth multi-usuário
MCP_DCR_SERVER_SECRET	Auto-hospedagem	--	Segredo compartilhado OAuth multi-usuário, 32+ bytes aleatórios (DCR_SERVER_SECRET legado ainda é aceito)
HOST	Não	0.0.0.0	Endereço de bind
PORT	Não	8080	Porta HTTP

Credenciais do modo usuário (substituições opcionais): TELEGRAM_API_ID e TELEGRAM_API_HASH vêm com padrões públicos de desenvolvimento integrados, então apenas TELEGRAM_PHONE é necessário para iniciar o fluxo de telefone + OTP. TELEGRAM_SESSION_NAME e TELEGRAM_DATA_DIR personalizam o local do arquivo de sessão do Telethon. Não existe variável de ambiente TELEGRAM_PASSWORD — o 2FA de retransmissão HTTP é inserido pela interface web; a autenticação CLI local solicita interativamente e nunca armazena no ambiente.

CLI

O script de console better-telegram-mcp (instalado por uvx / pip) inicia o servidor quando executado sem subcomando, e expõe alguns subcomandos de operador para configuração local de usuário único e diagnósticos. Qualquer flag que não seja um subcomando é passada diretamente ao servidor (ex.: --http).

better-telegram-mcp            # start the MCP server (stdio, bot mode by default)
better-telegram-mcp --http     # start in HTTP mode
better-telegram-mcp --version  # print the version

Subcomandos (better-telegram-mcp <subcommand>):

Subcomando	Uso	Descrição
auth	auth --bot-token <token> ou auth --phone <+number>	Autenticar esta máquina (usuário único). O modo bot valida o token; o modo telefone executa o fluxo interativo de OTP/2FA e armazena a sessão do Telethon em disco
login	Mesmos argumentos que auth	Alias obsoleto de auth
logout	logout	Revogar a sessão do Telegram no servidor, excluir o arquivo de sessão local e limpar as credenciais salvas
config	config status, config delete [--yes]	Mostrar ou excluir a configuração de credenciais locais salvas (substituições de ambiente ainda têm precedência na inicialização do servidor)
relay	relay status, relay open, relay reset	Inspecionar, abrir (imprimir uma nova URL de configuração) ou redefinir a sessão de configuração de retransmissão no navegador
doctor	doctor	Imprimir diagnósticos do ambiente — versão do Python, backend de credenciais, estado de configuração + retransmissão e modo de transporte

# Bot mode: validate a bot token and save it to the local config
better-telegram-mcp auth --bot-token 123456:ABC-DEF

# User mode: interactive phone + OTP (+ 2FA if enabled) sign-in
better-telegram-mcp auth --phone +15551234567

# Remove local credentials and revoke the session
better-telegram-mcp logout

O comando auth, seu alias obsoleto login e logout são de usuário único e apenas para máquina local — eles gravam a sessão do Telethon em disco e a configuração criptografada de usuário único, então execute-os na máquina que hospeda o servidor stdio. Para implantações HTTP remotas / multi-usuário, as credenciais são inseridas pelo formulário de retransmissão no navegador (consulte o endpoint remoto e Configuração).

Documentação

Documentação completa em mcp.n24q02m.com/servers/better-telegram-mcp/setup/:

• Configuração — métodos de instalação para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Visão geral dos modos — stdio (local, usuário único) e HTTP (remoto, OAuth 2.1)
• Configuração multi-usuário — modelo de credenciais por sub do JWT

Instalar com agente de IA — cole isto no seu agente de codificação de IA:

Instale o servidor MCP better-telegram-mcp seguindo os passos em https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Ferramentas

Ferramenta	Ações	Descrição
message	send, edit, delete, forward, pin, react, search, history	Enviar, editar, excluir, encaminhar mensagens. Fixar, reagir, pesquisar, navegar no histórico
chat	list, info, create, join, leave, members, admin, settings, topics	Listar e gerenciar chats, grupos, canais. Membros, administração, tópicos de fórum
media	send_photo, send_file, send_voice, send_video, download	Enviar fotos, arquivos, notas de voz, vídeos. Baixar mídia de mensagens
contact	list, search, add, block	Listar, pesquisar, adicionar contatos. Bloquear/desbloquear usuários (somente modo usuário)
config	status, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete	Status do servidor, configurações de tempo de execução, cache, configuração de credenciais (retransmissão, status, redefinição, conclusão)
help	--	Documentação completa para qualquer tópico
config__open_relay	--	Re-disparar o fluxo de configuração de retransmissão sem configuração (imprime uma nova URL de retransmissão para o formulário do navegador). Registrado via mcp-core's register_open_relay_tool para que um LLM possa reiniciar a configuração sem reinicialização manual

Recursos MCP

URI	Conteúdo
telegram://docs/messages	Referência de operações de mensagem
telegram://docs/chats	Referência de gerenciamento de chat
telegram://docs/media	Referência de envio/download de mídia
telegram://docs/contacts	Referência de gerenciamento de contatos
telegram://stats	Toda a documentação combinada

Comparação

Como o better-telegram-mcp se posiciona em relação aos concorrentes diretos em cada pilar:

Capacidade	better-telegram-mcp	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Modo Bot API (token de bot)	Sim (httpx)	Não	Não	Sim
Modo de conta de usuário MTProto	Sim (Telethon)	Sim	Sim	Não
Enviar / editar / excluir mensagens	Sim	Sim	Não (somente leitura, somente rascunho)	Sim (somente envio)
Download de mídia de mensagens	Sim	Sim	Sim	Não (somente envio)
Gerenciamento de contatos (adicionar / bloquear)	Sim (modo usuário)	Sim	Parcial (somente listar)	Não
Autenticação OTP via web / navegador	Sim (formulário relay, headless)	Não (string de sessão CLI)	Não (login CLI)	Não (token de bot pré-definido)
Remoto multi-usuário, isolamento por usuário	Sim (backends por JWT-sub)	Não	Não	Não
Proteção SSRF	Sim (validação de URL + DNS-rebinding)	?	?	Não
Prevenção de path traversal	Sim (caminho real com raiz permitida)	Sim	?	Não
Auto-hospedável	Sim	Sim	Sim	Sim

Segurança

• Proteção SSRF — Todas as URLs validadas contra faixas de IP internas/privadas, DNS rebinding bloqueado
• Prevenção de Path Traversal — Caminhos de arquivo validados, diretórios sensíveis bloqueados
• Segurança do arquivo de sessão — Permissões 600, 2FA somente via interface web (nunca armazenado em variáveis de ambiente)
• Sanitização de erros — Credenciais nunca vazadas em mensagens de erro

Compilar a partir do código-fonte

git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp

Implantar no Cloudflare

Execute seu próprio servidor better-telegram-mcp multi-usuário sem servidor no Cloudflare (Worker + Container + KV).

Pré-requisitos: uma conta Cloudflare no plano Workers Paid — necessário para Containers (o nível gratuito do Cloudflare não inclui Containers) — e a CLI wrangler.

1. git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp
2. wrangler login
3. Provisione o namespace KV e cole o id dele em wrangler.jsonc:

   wrangler kv namespace create better-telegram-kv
   

4. Envie a imagem do container para o seu registro gerenciado do Cloudflare (CF Containers não podem puxar de registros externos diretamente) e defina <YOUR_ACCOUNT_ID> em wrangler.jsonc:

   docker pull ghcr.io/n24q02m/better-telegram-mcp:beta
   docker tag ghcr.io/n24q02m/better-telegram-mcp:beta better-telegram-mcp:beta
   wrangler containers push better-telegram-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/better-telegram-mcp:beta
   

5. Defina <YOUR_PUBLIC_URL> (ex.: https://telegram.example.com) e <YOUR_WORKER_DOMAIN> (ex.: telegram.example.com) em wrangler.jsonc, e então defina os segredos:

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put MCP_DCR_SERVER_SECRET
   

   CREDENTIAL_SECRET é OBRIGATÓRIO: ele deriva uma chave de assinatura OAuth determinística para que a identidade do usuário sobreviva à recriação do container. MCP_RELAY_PASSWORD controla o formulário de configuração do navegador (porta de entrada compartilhada do Gate A); MCP_DCR_SERVER_SECRET (32+ bytes aleatórios) marca a implantação como intencionalmente multi-usuário.
6. wrangler deploy, e então conclua a configuração no formulário relay do navegador no domínio do seu Worker — cada usuário insere seu próprio token de bot ou telefone + OTP lá, então nenhuma credencial Telegram por usuário fica no Worker.

O armazenamento é mapeado para o Cloudflare via MCP_STORAGE_BACKEND=cf-kv (a configuração criptografada). NÃO defina MCP_AUTH_DISABLE em uma implantação compartilhada/pública — isso colapsa todos os usuários em um único balde de credenciais.

Modelo de confiança

Este plugin implementa TC-NearZK (em memória, efêmero). Veja modelo de confiança do mcp-core para a classificação completa.

Modo	Armazenamento	Criptografia	Quem pode ler seus dados?
HTTP hospedado n24q02m (padrão)	Em memória dict[sub] = MTProtoSession	Somente no processo	Processo do servidor (limpo no reinício)
HTTP auto-hospedado	Igual ao hospedado	Igual	Somente você (admin = usuário)
stdio	~/.config/mcp/config.enc (credenciais) + ~/.better-telegram-mcp/<name>.session (sessão Telethon)	AES-GCM, chave vinculada à máquina	Somente o usuário do seu SO (permissão de arquivo 0600)

Nome de usuário do workspace (formulário de configuração HTTP)

O formulário de configuração do navegador tem um campo opcional nome de usuário do workspace. Inserir o mesmo nome de usuário sempre o leva ao mesmo balde por sub, então sua sessão permanece acessível após uma reautorização e entre dispositivos, em vez de ficar vinculada ao sujeito único cunhado para cada ida e volta de /authorize. Deixar em branco mantém o comportamento anterior por autorização.

Limite de confiança: quando o formulário é protegido por um MCP_RELAY_PASSWORD compartilhado, o nome de usuário é uma chave de partição, não um segredo — qualquer pessoa que conheça essa senha pode digitar qualquer nome de usuário e alcançar esse balde. Isso é aceitável para um grupo confiável; uma implantação multi-tenant não confiável precisa de um segredo por usuário ou OAuth delegado em vez disso.

Migração única: usuários existentes devem reautenticar uma vez após esta mudança. Nada é excluído; sessões armazenadas sob o antigo sujeito aleatório são simplesmente não mais endereçadas.

Licença

Apache-2.0 — Veja LICENSE.