Servidor MCP de Telegram: ler e enviar mensagens do Telegram com um agente

Um servidor MCP de Telegram dá quatro ações a um agente: ler conversas, enviar uma mensagem, responder em uma thread existente e abrir um chat com alguém que já escreveu para o seu bot. Ele roda na Bot API oficial, então um único token é toda a instalação. No Telegram não existem posts. Tudo abaixo foi conferido em 13 de novembro de 2026.

O que um servidor MCP de Telegram sabe fazer

O Telegram é um canal de mensagens. Como o WhatsApp, não tem feed, não tem objeto post e portanto não tem alcance, impressões nem taxa de engajamento. Então a lista de ferramentas que um agente recebe via MCP é curta: listar conversas, ler o histórico de mensagens de uma delas, enviar texto, responder em uma thread, abrir uma conversa com um id de chat conhecido.

No PlugKit as ferramentas se chamam list_conversations, get_conversation, list_messages, send_message, send_dm, create_conversation e sync_conversations, e a caixa de entrada é unificada: as mesmas quatro ferramentas leem Instagram, Facebook, WhatsApp e Telegram. Isso pesa mais do que parece. Um agente que triaga sua caixa não deveria precisar de uma ferramenta diferente por rede, porque no instante em que precisa, é você que está escrevendo a lógica de roteamento no prompt.

O que você não vai encontrar: agendamento, analítica, moderação de comentários. Qualquer servidor que anuncie analítica de Telegram está descrevendo estatísticas de canal tiradas de outra superfície, ou algo que não existe na Bot API.

Por que a Bot API faz deste o MCP mais fácil de montar

Qualquer outra plataforma desta categoria faz você registrar um app, pedir scopes, passar por uma revisão e depois renovar um token para sempre. O servidor MCP do Instagram precisa de uma conta profissional, um app da Meta e uma revisão de app. O do LinkedIn precisa de acesso de parceiro para metade dos endpoints.

O Telegram pede uma conversa com outro bot. Você escreve para @BotFather, envia /newbot, escolhe um nome e um nome de usuário terminado em bot, e ele te entrega um token no formato 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Esse token é a credencial. Ele não expira, não há ciclo de renovação e não há fila de revisão.

As chamadas vão para https://api.telegram.org/bot<token>/METHOD_NAME por HTTPS, GET ou POST. O que também significa que o token fica no caminho da URL em toda requisição, então ele vai parar nos logs de proxy e no histórico do shell. Trate como senha, e use /revoke no BotFather assim que um vazar.

No PlugKit a ferramenta que faz isso é connect_telegram: você dá o token do BotFather, ele valida junto ao Telegram antes de armazenar, e o bot aparece como uma conta conectada. Sem ida e volta de OAuth, porque não há nada a autorizar.

A única regra que trava o seu agente de vez

A própria documentação do Telegram diz em uma linha: «Bots can't start conversations with users. A user must either add them to a group or send them a message first.»

É o equivalente no Telegram da janela de 24 horas da Meta, só que permanente em vez de um cronômetro. Seu agente não pode procurar um nome de usuário e escrever para ele. Ele só pode responder a quem já apertou Start no seu bot, ou falar em grupos onde o bot foi adicionado.

A consequência prática para um fluxo de agente: uma lista de conversas não é uma lista de contatos que você pode mirar. Antes de construir qualquer coisa que notifique usuários, você precisa de um caminho que os faça abrir o bot primeiro, normalmente um deep link no formato t.me/yourbot?start=payload, onde a carga útil chega na primeira mensagem /start e te diz quem são.

Dentro dos grupos existe um segundo limite que vale conhecer antes de depurar por uma hora. Por padrão, um bot em um grupo só recebe as mensagens que lhe dizem respeito: comandos, respostas às próprias mensagens, menções. O Telegram chama isso de modo privacidade. Se seu agente precisa ler uma conversa de grupo inteira, o modo privacidade tem que ser desligado primeiro no BotFather, e o bot precisa ser removido e adicionado de novo ao grupo para a mudança valer.

getUpdates ou webhook: como as mensagens chegam ao servidor

A Bot API oferece exatamente dois jeitos de receber mensagens, e eles são mutuamente exclusivos. Ativar um desativa o outro, que é de longe a causa mais comum de «meu bot parou de receber qualquer coisa».

• getUpdates é long polling. Você pede as atualizações com um offset, um limit entre 1 e 100, e um timeout. Bom para desenvolvimento local.
• setWebhook faz o Telegram mandar cada atualização por POST para uma URL HTTPS sua, com max_connections entre 1 e 100 e um cabeçalho secret_token que você deveria sempre definir. É o que um servidor hospedado usa.

Se você roda um servidor MCP local no seu notebook, você está no getUpdates, tendo escolhido ou não, porque o Telegram não entrega webhook para uma máquina sem endereço HTTPS público. Um servidor hospedado registra o webhook uma vez e as atualizações chegam sem polling. Os trade-offs são os mesmos cobertos em MCP server hosting.

Os limites de frequência que transformam um disparo em 429

O Telegram publica esses números no FAQ de bots, e eles são mais rígidos do que quase todo mundo espera, porque nada avisa até o 429 chegar.

Uma mensagem por segundo por chat soa generoso até um agente resolver responder uma pergunta longa em cinco parágrafos, cada um como mensagem separada. Diga para ele mandar uma mensagem, não uma thread. E se você se sentir tentado a fazer um agente disparar um aviso para alguns milhares de chats, é a linha das 30 por segundo: um disparo para 3000 pessoas leva pelo menos 100 segundos mesmo com tudo saudável.

Conecte no Claude, ChatGPT ou Cursor

O servidor MCP hospedado do PlugKit cobre o Telegram junto com as plataformas de publicação, e essa é a razão para usar um endpoint só em vez de um servidor exclusivo de Telegram: o mesmo agente que responde uma mensagem do Telegram pode publicar o post do Instagram sobre o qual falaram com ele. Ele roda em https://api.plugkit.co/mcp por Streamable HTTP, seguindo a revisão da especificação MCP de 28 de julho de 2026, com 103 ferramentas e três workflows prontos em 13 de novembro de 2026.

No Claude Code:

claude mcp add -t http plugkit https://api.plugkit.co/mcp

Nos apps do Claude é Customize, depois Connectors, depois Add, e então um conector personalizado com a mesma URL. O ChatGPT aceita em Add custom MCP server. Cursor e VS Code aceitam um link de um clique ou algumas linhas de JSON. A autenticação é OAuth 2.1 com PKCE e sem client secret, com mcp:read para ler conversas e mcp:write para enviar. Comece no mcp:read: ler uma caixa de entrada é reversível, enviar uma mensagem no Telegram não é.

O PlugKit custa US$ 49 por mês para 5 contas conectadas, cancele quando quiser, ou US$ 97 para 30. Sete dias grátis, com cartão no cadastro e nada cobrado antes do dia 7. As mensagens do Telegram em si não custam nada, já que a Bot API não cobra por mensagem fora das transmissões pagas.

Se você só precisa do Telegram e de mais nada, escreva você mesmo. Um token de bot e 40 linhas contra sendMessage é honestamente o trabalho de uma manhã, e segue sendo a resposta certa para um projeto de um canal só. O argumento para um servidor hospedado é a segunda plataforma, onde começa o trabalho com credenciais. MCP diante de uma API comum é a versão longa desse trade-off.

Perguntas frequentes

Existe um servidor MCP de Telegram oficial?

Não. O Telegram publica a Bot API; qualquer camada MCP em cima é de terceiros. Vale checar antes de instalar um, porque alguns servidores da comunidade dirigem uma conta de usuário pela API cliente MTProto em vez de um bot, o que põe sua conta pessoal em risco em vez de um bot que você pode revogar.

O Claude consegue enviar mensagens no Telegram?

Sim, por um servidor MCP ligado à Bot API. O Claude não tem acesso próprio ao Telegram. Com o servidor adicionado, enviar é uma chamada de ferramenta, sujeita à mesma regra de qualquer bot: quem recebe precisa ter iniciado o seu bot ou dividir um grupo com ele.

Por que meu bot não consegue escrever primeiro para um usuário?

Porque o Telegram proíbe isso por desenho. Um usuário precisa mandar uma mensagem ao bot ou adicioná-lo a um grupo antes de o bot poder escrever para ele. O contorno habitual é um deep link, t.me/yourbot?start=payload, que abre o bot com uma carga útil que você consegue ligar ao usuário.

Preciso de OAuth para um servidor MCP de Telegram?

Para o Telegram, não. A Bot API se autentica com um token do BotFather e mais nada. Você ainda pode querer OAuth entre o seu agente e o servidor MCP, que é outra camada e está coberta em MCP server OAuth authentication.

Um bot do Telegram consegue ler todas as mensagens de um grupo?

Só se o modo privacidade estiver desligado. Por padrão, um bot adicionado a um grupo recebe comandos, respostas às próprias mensagens e menções, e mais nada. Você desliga o modo privacidade no BotFather, depois remove e adiciona o bot de novo ao grupo para a mudança valer.

AB

Antoine BlancoFundador da PlugKit. Gerencia as próprias contas de Instagram, YouTube e X pela API e pelo servidor MCP descritos aqui.