Telegram MCP Server

Conecte-se à sua conta do Telegram para ler e enviar mensagens.

GitHub
7
Experimente este MCPPatrocinado

Documentação

Telegram MCP Server

Conecte o Claude à sua conta do Telegram para ler e enviar mensagens.

Recursos

A maioria dos chats, usuários e grupos pode ser referenciada por ID numérico, @username, número de telefone, link do t.me ou o literal "me" — o servidor resolve isso para você (e aquece o cache de entidades do Telethon automaticamente para que IDs brutos também funcionem).

Ferramentas Disponíveis

Leitura

  • get_me – Informações sobre a conta autenticada
  • get_chats – Lista paginada de chats (nomes, IDs, contagens de não lidas, estado de fixação); suporta chats arquivados
  • get_messages – Histórico de mensagens paginado de um chat (marca como lido); inclui informações de mídia e reações
  • search_messages – Pesquisa por texto, globalmente ou em um único chat
  • get_pinned_messages – Lista mensagens fixadas em um chat
  • get_entity_info – Busca um usuário/grupo/canal por ID, nome de usuário, telefone ou link
  • get_participants – Lista membros de um grupo ou canal

Envio e edição

  • send_message – Envia texto (Markdown), opcionalmente como resposta
  • edit_message – Edita uma mensagem que você enviou
  • delete_messages – Exclui mensagens (para todos ou apenas para você)
  • forward_messages – Encaminha mensagens entre chats
  • send_reaction – Adiciona ou remove uma reação de emoji
  • pin_message / unpin_message – Fixa ou desafixa mensagens
  • mark_messages_read – Marca mensagens não lidas de um chat como lidas

Mídia

  • send_file – Envia uma foto, vídeo, documento ou nota de voz do disco
  • download_media – Baixa a mídia anexada de uma mensagem para o disco

Contatos e usuários

  • get_contacts – Lista contatos salvos
  • add_contact / delete_contact – Gerencia contatos
  • block_user / unblock_user – Gerenciamento de bloqueio

Gerenciamento de chats e canais

  • create_group – Cria um grupo básico
  • create_channel – Cria um canal ou supergrupo
  • join_chat / leave_chat – Entra (por nome de usuário ou link de convite) ou sai
  • archive_chat – Arquiva / desarquiva um chat
  • mute_chat – Silencia / ativa notificações

Redação com consciência de estilo

  • get_conversation_context – Mensagens recentes + seu guia convostyle.txt para que o Claude combine com seu estilo de texto

Guia de Configuração

Passo 1: Obtenha as Credenciais da API do Telegram

  1. Acesse https://my.telegram.org/apps
  2. Faça login e crie um aplicativo
  3. Salve seu API ID e API Hash

Passo 2: Instalação

# Clone the repository
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

# Set up Python environment
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Passo 3: Configuração

# Copy the example file
cp .env.example .env

# Edit .env and add your API credentials:
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here

Passo 4: Autenticação

A partir da raiz do repositório:

uv run telegram-auth

Siga as instruções:

  • Digite seu número de telefone (com código do país, ex.: +1234567890)
  • Digite o código enviado para seu Telegram
  • Digite sua senha de 2FA, se tiver uma

Isso grava TELEGRAM_SESSION_STRING no seu .env.

Passo 5: Adicionar ao Claude Desktop

Encontre o arquivo de configuração do Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione esta configuração (substitua o caminho pela localização do seu clone):

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-telegram", "run", "telegram-mcp"]
    }
  }
}

Se uv não estiver no PATH do Claude Desktop, use o caminho absoluto (which uv). Alternativamente, aponte command para o Python do seu venv e use ["-m", "mcp_telegram"] como argumentos, com cwd definido para a raiz do repositório.

Reinicie o Claude Desktop.

Uso

Após a configuração, você pode pedir ao Claude para:

  • "Verificar minhas mensagens do Telegram"
  • "Enviar uma mensagem para [nome do contato]"
  • "Quais são meus chats não lidos?"
  • "Responder à última mensagem de [nome do contato]"

Guia de Estilo (Opcional)

Crie src/mcp_telegram/convostyle.txt para ajudar o Claude a combinar seu estilo de texto:

I text casually with friends, formally with work contacts.
I use emojis sparingly and prefer short messages.

Solução de Problemas

Problemas de Autenticação

Se a autenticação falhar:

  1. Verifique suas credenciais da API em .env
  2. Remova a linha TELEGRAM_SESSION_STRING de .env
  3. Execute uv run telegram-auth novamente

Erros Comuns

  • "Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": Arquivo .env ou credenciais ausentes
  • "Session string is invalid or expired": Execute a autenticação novamente
  • Senha de 2FA não aparecendo: Isso é normal - continue digitando

Requisitos

  • Python 3.10+
  • Claude Desktop
  • Conta do Telegram

Licença

Apache 2.0