Telegram MCP

telegram-mcp

Um servidor Model Context Protocol (MCP) para interagir com o Telegram usando mtcute.

Recursos

• Enviar mensagens de texto para chats
• Aguardar mensagens recebidas em chats específicos
• Ler mensagens de chats
• Pesquisar mensagens
• Listar e obter informações sobre diálogos (chats)
• Obter mensagens recentes de todos os chats
• Definir e inspecionar IDs de status de emoji para contas e canais

Configuração

Instalação

Opção 1: Baixar Binário Pré-compilado

Baixe a versão mais recente para sua plataforma na página de releases:

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz
• macOS (Intel): telegram-mcp-darwin-x64.tar.gz
• Linux: telegram-mcp-linux-x64.tar.gz
• Windows: telegram-mcp-win-x64.exe.zip

Extraia o arquivo e torne o binário executável (sistemas Unix):

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

Opção 2: Compilar a partir do Código-fonte

1. Clone o repositório e instale as dependências:

   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install
   

2. Compile o executável:

   bun run build
   

Configuração Inicial (Somente na Primeira Vez)

1. Obtenha suas credenciais da API do Telegram em https://my.telegram.org

2. Execute a configuração inicial para autenticar com o Telegram:

   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp
   

   O servidor irá:

   • Solicitar que você insira seu número de telefone
   • Enviar um código de verificação via Telegram
   • Pedir o código de verificação
   • Exibir o caminho absoluto de armazenamento (você precisará dele para a configuração do MCP)

3. Anote o caminho de armazenamento exibido na saída. Ele será algo como:

   Storage path: /Users/username/telegram-mcp/bot-data/session
   

Uso

Como Servidor MCP

Adicione à configuração do Claude Desktop usando o caminho de armazenamento da configuração inicial:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

Importante: O TELEGRAM_STORAGE_PATH deve ser o caminho absoluto exibido durante a configuração inicial. Isso garante que o servidor MCP use a sessão autenticada.

Ferramentas Disponíveis

Ferramentas de Mensagem

• messages_sendText - Enviar uma mensagem de texto para um chat

  • chatId (obrigatório): ID do Chat/Usuário ou nome de usuário
  • text (obrigatório): Texto da mensagem a enviar
  • replyToMessageId: ID opcional da mensagem para responder

• messages_getHistory - Obter histórico de mensagens de um chat

  • chatId (obrigatório): ID do Chat/Usuário ou nome de usuário
  • limit: Número de mensagens (padrão: 100, máximo: 100)
  • offsetId: ID da mensagem para paginação

• messages_search - Pesquisar mensagens

  • query (obrigatório): Consulta de pesquisa
  • chatId: Chat específico para pesquisar (opcional)
  • limit: Número de resultados (padrão: 50)

• messages_getRecent - Obter mensagens recentes de todos os chats

  • limit: Número de chats (padrão: 10)
  • messagesPerChat: Mensagens por chat (padrão: 10)

Ferramentas Interativas

• wait_for_reply - Aguardar a próxima mensagem em um chat
  • chatId (obrigatório): ID do Chat/Usuário ou nome de usuário para aguardar uma mensagem
  • timeoutSeconds: Tempo limite em segundos (padrão: 60, máximo: 300)

Ferramentas de Status

• status_getCurrent - Obter o status de emoji atual de um peer

  • peerId: Peer de destino, padrão é self

• status_setEmoji - Definir ou limpar um status de emoji

  • peerId: Peer de destino, padrão é self
  • emojiId: ID do documento de emoji personalizado, obrigatório a menos que clear=true
  • isCollectible: Defina true quando emojiId for um ID colecionável
  • until: Carimbo de data/hora ISO-8601 opcional ou string de carimbo de data/hora Unix
  • clear: Limpar o status atual em vez de definir um

• status_listAvailable - Listar IDs de status de emoji padrão disponíveis

  • scope: self ou channel (padrão: self)
  • limit: Máximo de IDs a retornar (padrão: 100)

• status_listCollectibles - Listar IDs colecionáveis próprios utilizáveis como status de emoji pessoal

  • owner: Peer para inspecionar, padrão é self
  • limit: Máximo de colecionáveis a retornar (padrão: 100)

Ferramentas de Diálogo

• dialogs_list - Listar todos os diálogos

  • limit: Máximo de diálogos (padrão: 50)
  • filter: Opções de filtro (onlyUsers, onlyGroups, onlyChannels)

• dialogs_getInfo - Obter informações detalhadas do diálogo

  • chatId (obrigatório): ID do Chat/Usuário ou nome de usuário

Desenvolvimento

Execute em modo de desenvolvimento:

bun run dev

O servidor armazena dados de sessão no diretório bot-data/.