mcp-telegram

Servidor MCP do Telegram usando User API (MTProto) com ACL de negação padrão, permissões granulares por chat, envio de arquivos, downloads de mídia e limitação de taxa

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-telegram

Um servidor MCP que conecta assistentes de IA como Claude à sua conta Telegram real via User API (MTProto). Não é um bot — Claude lê e envia mensagens como você.

Construído com gotd/td e o MCP Go SDK oficial.

Termos de Serviço da API do Telegram: Este projeto usa a User API do Telegram. Você deve obter seu próprio api_id e api_hash em my.telegram.org e cumprir os Termos de Serviço da API do Telegram. O uso indevido da User API (spam, envio em massa, raspagem de dados) pode resultar no banimento da sua conta. Você é o único responsável pelo uso desta ferramenta.

Recursos

Ferramenta	O que faz	Permissão necessária
`tg_me`	Retorna informações da conta atual	—
`tg_dialogs`	Lista os diálogos visíveis na lista de permissões da ACL	—
`tg_history`	Busca o histórico de mensagens com paginação, filtro por data e download de mídia	`read`
`tg_search`	Pesquisa mensagens em um chat por consulta de texto, com filtro opcional de remetente	`read`
`tg_send`	Envia uma mensagem de texto ou arquivo, com resposta opcional	`send`
`tg_forward`	Encaminha mensagens de um chat para outro	`read` + `send`
`tg_draft`	Salva um rascunho de mensagem (não envia)	`draft`
`tg_mark_read`	Marca um chat como lido	`mark_read`

Recursos adicionais:

Envio de arquivos e fotos
Encaminhamento de mensagens entre chats
Resposta a mensagens específicas
Download de fotos e documentos do histórico de mensagens
Filtro de histórico por intervalo de datas (since / until)
Referências de peer tipadas (user:ID, chat:ID, channel:ID) para evitar colisões de ID
Resolução preguiçosa de peers — evita erros de FLOOD_WAIT na inicialização
Limitação de taxa global no nível de RPC

O que você pode fazer com ela

Depois de conectado, você pode pedir ao seu assistente de IA coisas como:

Acompanhar mensagens

"Verifique minhas mensagens não lidas do Telegram e me dê um resumo"
"O que @alice escreveu nas últimas 24 horas?"
"Mostre-me as mensagens do chat Dev Team desde segunda-feira"

Responder e se comunicar

"Elabore uma resposta para a última mensagem de @bob — não envie ainda"
"Envie 'parece bom, vamos nos encontrar às 15h' para @alice"
"Responda à mensagem 1234 no chat do projeto com meu feedback"

Gerenciar sua caixa de entrada

"Marque tudo como lido no canal de notícias"
"Quais dos meus chats na lista de permissões têm mensagens não lidas?"
"Baixe as fotos das mensagens de hoje no chat de design"

Pesquisar e analisar

"Encontre todas as mensagens mencionando o deploy na última semana"
"Resuma a discussão no chat da equipe de ontem"
"Quais arquivos foram compartilhados no canal do projeto este mês?"

Comparação com chaindead/telegram-mcp

	mcp-telegram	chaindead/telegram-mcp
Controle de acesso	Lista de permissões ACL com negação padrão e permissões granulares por chat	Acesso total a todos os chats
Endereçamento de peers	Referências tipadas (`user:ID`, `chat:ID`, `channel:ID`)	Apenas IDs numéricos (propenso a colisões)
Configuração	Config YAML com expansão de variáveis de ambiente	Flags de linha de comando
Segurança na inicialização	Resolução preguiçosa de peers (sem chamadas de API em massa)	Resolução imediata (risco de FLOOD_WAIT)
Limitação de taxa	Middleware de token bucket integrado	Nenhum
Suporte a arquivos	Envia arquivos, fotos; baixa mídia do histórico	Apenas texto
Suporte a respostas	Sim	Não
Filtro por data	Sim	Não

Início rápido

Pré-requisitos

Go 1.26+
Uma conta Telegram
Credenciais de API de my.telegram.org (api_id e api_hash)

Instalação

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

NPX (sem necessidade de instalação):

npx @prgebish/mcp-telegram serve --config config.yaml

Binários pré-compilados (macOS / Linux / Windows):

Baixe em GitHub Releases.

Instalação via Go:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

A partir do código-fonte:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

Isso gera mcp-telegram (ou mcp-telegram.exe no Windows) no diretório atual.

Autenticação

Execute o comando de autenticação uma vez para criar um arquivo de sessão. Você será solicitado a informar seu número de telefone, o código de login e (se ativado) sua senha de 2FA.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

Configuração

Crie um config.yaml:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

Variáveis de ambiente na sintaxe ${...} são expandidas no momento do carregamento.

Configuração do cliente

O servidor se comunica via stdio — seu cliente MCP inicia e gerencia o processo.

Claude Code (CLI — adicione via comando):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json ou claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (Settings > MCP Servers > Add):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

Configuração

ACL

A ACL é de negação padrão. Apenas chats explicitamente listados em acl.chats são acessíveis, e somente com as permissões que você especificar.

Padrões de correspondência suportados:

Padrão	Exemplo	Descrição
`@username`	`@johndoe`	Correspondência por nome de usuário do Telegram (sem diferenciar maiúsculas/minúsculas)
`+phone`	`+79001234567`	Correspondência por número de telefone
`user:ID`	`user:123456789`	Correspondência de um usuário por ID numérico
`chat:ID`	`chat:987654321`	Correspondência de um grupo por ID numérico
`channel:ID`	`channel:2225853048`	Correspondência de um canal ou supergrupo por ID numérico

Tipos de permissão: read, send, draft, mark_read.

Se o mesmo peer corresponder a várias regras (por exemplo, via @username e user:ID), as permissões são mescladas — elas nunca se sobrepõem.

Limitação de taxa

A seção limits.rate configura um token bucket global que envolve todas as chamadas RPC do Telegram:

requests_per_second — taxa sustentada (padrão: 2.0)
burst — tamanho máximo de rajada (padrão: 3)

Download de mídia

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

Quando configurado, tg_history baixará automaticamente arquivos de mídia para o diretório especificado. O parâmetro download_to pode substituir o caminho, mas apenas para media.directory ou seus subdiretórios.

allowed_upload_dirs restringe quais diretórios tg_send pode ler arquivos. O envio de arquivos é desativado a menos que isso seja configurado.

Segurança

ACL de negação padrão — nenhum chat é acessível a menos que seja explicitamente incluído na lista de permissões
Limite do sistema de arquivos — tg_send só pode ler arquivos de allowed_upload_dirs; download_to é restrito a subdiretórios de media.directory
Permissões do arquivo de sessão — aplicadas como 0600 (somente leitura/escrita pelo proprietário)
Sem registro de segredos — hashes de API, tokens de sessão e chaves de autenticação nunca são gravados em logs
Sem exposição de hashes de acesso — hashes de acesso internos do Telegram são removidos de toda a saída das ferramentas
Limitação de taxa — evita uso acidental indevido da API
Fuso horário local — os filtros de data usam o fuso horário do seu sistema, não UTC

Licença

MIT

Se você achar este projeto útil, por favor, dê uma estrela — isso ajuda outras pessoas a descobri-lo.