MCP Telegram Server

Um servidor MCP para interagir com o Telegram. Ele permite pesquisar, enviar mensagens e gerenciar chats usando a API do Telegram.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Telegram Server — Gateway do Telegram para o Model Context Protocol (MCP). 8 ferramentas eficientes em contexto, multi-tenant, ponte MTProto.

Experimente a Demonstração

Abra https://tg-mcp.l1979.ru/setup
Escaneie o código QR pelo aplicativo móvel do Telegram (Configurações → Dispositivos → Escanear QR) — sem digitar telefone, sem OTP, sem 2FA. Ou insira seu número de telefone como alternativa.
Copie seu token Bearer da página de sucesso

Depois escolha seu caminho:

Cliente MCP (assistentes de IA)

Na página de configuração, baixe o arquivo mcp.json
Adicione o servidor ao seu cliente de IA e pergunte: "envie um olá para minhas mensagens salvas no telegram"

API Direta (curl)

Execute o comando abaixo (substitua TOKEN pelo seu):

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello!"}}'

Como Funciona

Este servidor fica entre seu agente de IA e a API do Telegram:

Your agent → MCP/HTTP → this server → MTProto → Telegram

O que ele faz: Autentica você no Telegram (QR ou token de telefone/bot), expõe 8 ferramentas amigáveis para IA em vez de mais de 80 micro-APIs, e faz a ponte com MTProto bruto para usuários avançados. Multi-tenant — um servidor, muitos usuários, sessões isoladas.

Recursos

Recurso	Descrição
:building_construction: Transporte Duplo	Stdio para clientes MCP locais, HTTP para implantações remotas (`http-auth` em produção, `http-no-auth` opcional para desenvolvimento)
:closed_lock_with_key: Autenticação Multi-Usuário	Servidor `http-auth` compartilhado: um token Bearer por usuário, uma conta Telegram por conexão MCP. Login por QR para autenticação instantânea — sem telefone/OTP/2FA.
:dart: Otimizado para IA	8 ferramentas consolidadas vs mais de 80 micro-ferramentas — design eficiente em contexto, API amigável para LLM, MCP ToolAnnotations
:globe_with_meridians: Ponte HTTP-MTProto	Acesso direto via curl a qualquer método da API do Telegram com resolução de entidades e proteções de segurança
:shield: ACL de Sessão	Limites opcionais por principal em `http-auth` (`ACL_ENABLED`) — canais de chat, `read_only`, `blocked_peers`, `allow_mtproto`, `ACL_DENY_UNLISTED_PRINCIPALS`; veja SECURITY.md
:tv: Configuração por QR e Web	Escaneie o QR pelo Telegram móvel para autenticação instantânea (sem telefone/OTP/2FA) ou use telefone/código/2FA como alternativa — disponível em `/setup`
:label: Um Agente, Múltiplas Contas	`PREFIX_MCP_TOOLS_WITH_ACCOUNT` opcional — quando um agente usa várias conexões MCP (mesmo servidor, tokens diferentes), prefixa os nomes das ferramentas para evitar colisões; não é necessário para hospedagem multi-usuário padrão
:rocket: Suporte a Proxy MTProto	Conecte via proxy MTProto com Fake TLS automático (prefixo EE) e detecção padrão de proxy
:card_file_box: Gerenciamento Unificado de Sessões	Sistema único de configuração para setup e servidor; arquivos de sessão por token em hosts multi-usuário compartilhados
:cloud: Armazenamento de Sessão S3	Armazene sessões em armazenamento de objetos compatível com S3 para implantações efêmeras (Smithery, Fly.io, Railway)
:mag_right: Busca Inteligente	Busca global e por chat com suporte a múltiplas consultas e deduplicação inteligente
:mag: API de Mensagens Unificada	Ferramenta única `get_messages` para busca, navegação, leitura por IDs e respostas — 5 modos em uma
:speech_balloon: Respostas Universais	Obtenha respostas de posts de canais, tópicos de fórum ou qualquer mensagem com um parâmetro
:busts_in_silhouette: Descoberta Inteligente de Contatos	Busque usuários, grupos, canais com esquemas de entidades uniformes, detecção de fórum, enriquecimento de perfil
:file_folder: Filtragem por Pastas	Filtre chats por pasta de diálogo (arquivados, pastas personalizadas) com ID inteiro ou correspondência de nome
:envelope: Mensagens Avançadas	Envie, edite, responda, poste em tópicos de fórum, formatação, anexos de arquivos e mensagens para números de telefone
:paperclip: Manipulação Segura de Arquivos	Compartilhamento de mídia rica com proteção SSRF, limites de tamanho, suporte a álbuns, streaming opcional de anexos HTTP
:outbox_tray: Uploads de Arquivos Inline	Uploads de arquivos via URI de dados (base64) no parâmetro `files` — funcionam em todos os modos de transporte, nomes de arquivos preservados, imagens enviadas como fotos
:microphone: Transcrição de Voz	Conversão automática de fala em texto para contas Premium com processamento paralelo e polling
:zap: Alta Performance	Operações assíncronas, consultas paralelas e agrupamento consciente de memória
:shield: Confiabilidade em Produção	Reconexão automática, logging configurável, tratamento abrangente de erros

Início Rápido

1. Instale e autentique

Caminho mais rápido (servidor remoto): Abra /setup → escaneie o QR → copie o token (veja Experimente a Demonstração).

Caminho via CLI (stdio local): Execute fast-mcp-telegram-setup uma vez para criar uma sessão do Telegram — depois fast-mcp-telegram a serve:

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --phone-number="+123456789"

Alternativa com token de bot (sem telefone, sem OTP): Defina BOT_API_TOKEN em vez de --phone-number. Veja o Guia de Instalação.

2. Configure o Cliente MCP

Modo stdio (local): Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json) — stdio (entrada/saída padrão) é o transporte padrão para clientes MCP locais:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["fast-mcp-telegram"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash"
      }
    }
  }
}

Modo http-auth (remoto): Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "url": "https://tg-mcp.l1979.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Obtenha seu token escaneando o código QR na página de configuração ou veja o Guia de Instalação para implantar seu próprio servidor.

3. Comece a Usar

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello!"}}

Implante em Servidor Remoto

Implante seu próprio servidor MCP em um VDS — veja o Guia de Instalação para instruções passo a passo.

Ferramentas Disponíveis

Ferramenta	Finalidade	Recursos Principais
`search_messages_globally`	Busca em todos os chats	Consultas de múltiplos termos, filtro por data, filtro por tipo de chat
`get_messages`	Recuperação unificada de mensagens	Busca/navegação, leitura por IDs, obtenção de respostas (posts/tópicos/mensagens), filtro por data em todos os modos
`send_message`	Enviar nova mensagem	Anexos de arquivos (URLs/locais/URIs de dados), formatação clássica (markdown/html), `parse_mode=rich` Mensagens Rich, resposta a tópicos de fórum
`edit_message`	Editar mensagem existente	Formatação clássica ou `parse_mode=rich`
`find_chats`	Encontrar usuários/grupos/canais	Busca de múltiplos termos, descoberta de contatos, filtragem por pasta, consulta por nome de usuário/telefone
`get_chat_info`	Obter informações detalhadas de perfil	Contagem de membros, bio/sobre, status online, tópicos de fórum, grupos em comum, dados enriquecidos
`send_message_to_phone`	Enviar mensagens para números de telefone	Gerenciamento automático de contatos, limpeza opcional, suporte a arquivos (URLs/URIs de dados), `parse_mode=rich`
`invoke_mtproto`	API direta do Telegram (usuário avançado)	Métodos MTProto brutos, resolução de entidades, proteções de segurança — veja Ponte MTProto

Veja a Referência de Ferramentas para documentação detalhada com exemplos.

Documentação

Guia de Instalação - Configuração local e implantação em servidor remoto
Referência de Ferramentas - Documentação completa das ferramentas
Ponte MTProto - Acesso direto à API via curl
Contribuindo - Diretrizes para contribuidores
Segurança - Recursos de segurança e melhores práticas

Telemetria

Telemetria anônima de ferramentas desde v0.30.1 — heartbeat a cada 6h, sem coleta de credenciais ou conteúdo de mensagens. Desative com DO_NOT_TRACK=1. Veja ADR 0005.

Telemetria de fluxo de autenticação desde v0.38.0 — eventos atômicos durante a configuração (telefone, QR, token de bot, reautorização). Envio em buffer na conclusão do fluxo. Veja ADR 0008.

Licença

Licença MIT - veja LICENSE

mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram