better-telegram-mcp

Servidor MCP de nível de produção para Telegram com API de Bot em modo duplo + MTProto, 6 ferramentas compostas

Documentação

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.

ARQUIVADO em 2026-09-13 — Este repositório não é mais mantido. Use a API oficial do Telegram Bot em vez deste servidor MCP. Instalações existentes continuam funcionando, mas não recebem atualizações ou suporte.

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, fun...	Ferramentas
better-code-review-graph	Grafo de conhecimento para revisões de código eficientes em tokens — busca semântica e cham...	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 bo...	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 imagens e vídeos 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 reranking de texto Qwen3 leve via ONNX Runtime e GGUF	Biblioteca
skret	Segredos sem servidor.	CLI
tacet	Uma cascata neuro-simbólica autodestilante que amortiza o custo de LLM em conhecimento...	Ferramentas
web-core	Pacote de infraestrutura web compartilhada 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

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 do navegador em modo HTTP 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

O executável usa como padrão stdio para operação local de usuário único. O HTTP é ativado com --http, MCP_TRANSPORT=http ou TRANSPORT_MODE=http; HTTP é o modo de implantação para configuração de retransmissão do navegador e acesso opcional multiusuário. A matriz canônica de modos de pilha nomeia retransmissão remota HTTP como o padrão implantado do Telegram, portanto alterar o padrão do executável requer uma decisão e migração separadas do contrato de transporte. Este repositório não afirma silenciosamente que esses dois padrões já estão reconciliados.

Não há camadas de ponte daemon e nenhuma inicialização automática a partir de stdio. Consulte Visão geral dos modos para o modelo de transporte completo.

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

Instalação

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

Matriz de instalação

Cliente	Instalação
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-telegram-mcp@n24q02m-plugins` (modo bot stdio), ou `claude mcp add` como no bloco acima
Cursor / Windsurf / Gemini CLI / qualquer cliente MCP	JSON `mcpServers` na configuração do cliente — stdio `command`, ou `type: "http"` + `url` apontando para uma implantação

Guias completos por cliente: mcp.n24q02m.com/servers/better-telegram-mcp/setup/.

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 conclui a configuração de retransmissão do 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 para 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 recebe 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 do 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 do 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 ativar o modo HTTP (flag CLI `--http` ou `TRANSPORT_MODE=http` também funcionam)
`PUBLIC_URL`	Auto-hospedagem	--	URL pública do servidor; a presença ativa o ramo OAuth multiusuário
`MCP_DCR_SERVER_SECRET`	Auto-hospedagem	--	Segredo compartilhado OAuth multiusuário, 32+ bytes aleatórios (o `DCR_SERVER_SECRET` legado ainda é aceito)
`HOST`	Não	`0.0.0.0`	Endereço de vinculação
`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, portanto 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 da 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 (por exemplo, --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 variáveis 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 da retransmissão do 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 a máquina local — eles gravam a sessão do Telethon em disco e a configuração criptografada de usuário único, portanto execute-os na máquina que hospeda o servidor stdio. Para implantações HTTP remotas / multiusuário, as credenciais são inseridas pelo formulário de retransmissão do navegador (consulte o endpoint remoto e Configuração).

Documentação

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

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 multiusuário — modelo de credenciais por JWT-sub

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, ver histórico
`chat`	`list`, `info`, `create`, `join`, `leave`, `members`, `admin`, `settings`, `topics`	Listar e gerenciar chats, grupos, canais. Membros, admin, tópicos do 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 execução, cache, configuração de credenciais (relay, status, reset, complete)
`help`	--	Documentação completa para qualquer tópico
`config__open_relay`	--	Re-dispara o fluxo de configuração do relay sem configuração (imprime uma nova URL de relay 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 chats
`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 compara aos concorrentes diretos em cada pilar:

Capacidade	better-telegram-mcp	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Modo API de Bot (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 baseada em navegador / web	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	Sim (caminho real permitido na raiz)	?	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 better-telegram-mcp multi-usuário sem servidor no Cloudflare (Worker + Container + KV).

Implantação (gerenciada por CD)

Implantações gerenciadas passam por CI, nunca manualmente: o job deploy-cf em .github/workflows/cd.yml é executado após um release, faz checkout da tag lançada, compila a imagem imutável http na versão lançada, envia para o registro gerenciado do Cloudflare, implanta e bloqueia em uma verificação canary — uma instância gerenciada só pode, portanto, executar uma tag de release exata. wrangler deploy manual contra uma instância gerenciada/operada não é permitido: quebra a correspondência tag-de-release ↔ imagem-ao-vivo, e a próxima execução de CD a sobrescreveria.

O job é controlado pela variável de Actions do repositório CF_HOSTED_ENABLED — atualmente false, então releases não publicam um endpoint hospedado (de acordo com o Modelo de Confiança, não há endpoint público de Telegram hospedado por operador). Para executar sua própria instância, use as etapas de auto-hospedagem abaixo.

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

git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp
wrangler login
Provisione o namespace KV e cole seu id em wrangler.jsonc:
```
wrangler kv namespace create better-telegram-kv
```

Envie a imagem do container para seu registro gerenciado do Cloudflare (CF Containers não podem puxar de registros externos diretamente), depois 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

Defina <YOUR_PUBLIC_URL> (ex.: https://telegram.example.com) e <YOUR_WORKER_DOMAIN> (ex.: telegram.example.com) em wrangler.jsonc, depois 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 Gate A); MCP_DCR_SERVER_SECRET (32+ bytes aleatórios) marca a implantação como intencionalmente multi-usuário.
wrangler deploy, depois 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 de Telegram por usuário reside no Worker.

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

Modelo de Confiança

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

O projeto não opera mais um endpoint de Telegram hospedado por n24q02m. O modo HTTP está disponível apenas em infraestrutura que um operador implanta e controla.

Modo	Armazenamento	Criptografia	Quem pode ler seus dados?
HTTP auto-hospedado (opt-in)	`dict[sub] = MTProtoSession` em memória	Somente em processo	Processo do servidor controlado pelo operador (limpo na reinicialização)
stdio	`~/.config/mcp/config.enc` (credenciais) + `~/.better-telegram-mcp/<name>.session` (sessão Telethon)	AES-GCM, chave vinculada à máquina	Somente seu usuário do 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 de nome de usuário do workspace. Inserir o mesmo nome de usuário sempre o leva ao mesmo bucket por sub, então sua sessão permanece acessível após uma reautorização e entre dispositivos, em vez de estar 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 é controlado 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 bucket. 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.