MCP Telegram

Conecte Grandes Modelos de Linguagem ao Telegram por meio do Model Context Protocol (MCP).

Construído com Telethon, este servidor permite que agentes de IA interajam com o Telegram, habilitando recursos como enviar/editar/excluir mensagens, pesquisar conversas, gerenciar rascunhos, baixar mídias e muito mais usando o MTProto.

---

Sumário

• 🚀 Começando
  • Pré-requisitos
  • Instalação
• ⚙️ Uso
  • Login
  • Conectar ao servidor MCP
• 🧰 Ferramentas Disponíveis
  • 📨 Ferramentas de Mensagens
  • 🔍 Pesquisa e Navegação
  • 📝 Gerenciamento de Rascunhos
  • 📂 Manipulação de Mídia
• 🛠️ Solução de Problemas
• 🤝 Contribuindo
• 📝 Licença

---

🚀 Começando

Pré-requisitos

• Python 3.10 ou superior
• uv Instale por meio do guia oficial do uv.

Instalação

Instale a ferramenta CLI do mcp-telegram:

uv tool install mcp-telegram

⚙️ Uso

[!IMPORTANT] Certifique-se de ter lido e compreendido os Termos de Serviço do Telegram antes de usar esta ferramenta. O uso indevido desta ferramenta pode resultar em restrições na conta.

A ferramenta de linha de comando mcp-telegram é o seu ponto de entrada.

mcp-telegram --help # See all commands

Login

Primeiro, autentique-se com sua conta do Telegram:

mcp-telegram login

Este comando interativo solicitará:

• API ID e API Hash: Obtenha-os em my.telegram.org/apps.
• Número de telefone: Seu número de telefone registrado no Telegram (formato internacional, ex.: +1234567890).
• Código de verificação: Enviado para sua conta do Telegram no primeiro login.
• Senha 2FA: Se você tiver a autenticação de dois fatores habilitada.

Suas credenciais são armazenadas com segurança no arquivo de sessão para uso futuro.

[!WARNING] Mantenha suas credenciais de API privadas e nunca as compartilhe publicamente.

[!NOTE] Use mcp-telegram logout para sair da sessão atual ou mcp-telegram clear-session para remover todos os dados de sessão armazenados.

Conectar ao servidor MCP

Para usar o MCP Telegram com clientes MCP como Claude Desktop ou Cursor, você precisará configurar o servidor MCP. O processo de configuração varia conforme o cliente e o sistema operacional.

Para instruções detalhadas de configuração, consulte:

• Guia de Configuração do MCP para Claude Desktop
• Documentação do MCP para Cursor

O arquivo de configuração deve conter:

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

[!Note] Os caminhos de configuração variam conforme o sistema operacional e o cliente. Por exemplo:

• macOS: ~/Library/Application Support/Claude/ ou ~/.cursor/
• Windows: %APPDATA%\Claude\ ou %APPDATA%\Cursor\

[!IMPORTANT] Se o seu cliente não conseguir executar mcp-telegram mesmo estando acessível no terminal, tente usar o caminho completo para o executável. Você pode encontrá-lo executando which mcp-telegram (macOS/Linux) ou where mcp-telegram (Windows) no seu terminal. Substitua o valor de command na configuração pelo caminho completo.

Após salvar o arquivo de configuração, reinicie seu aplicativo.

🧰 Ferramentas Disponíveis

Aqui está uma lista abrangente de ferramentas que você pode usar para interagir com o Telegram por meio do MCP:

📨 Ferramentas de Mensagens

Ferramenta	Descrição
send_message	✉️ Envie mensagens de texto ou arquivos para qualquer usuário, grupo ou canal
edit_message	✏️ Modifique o conteúdo de mensagens enviadas anteriormente
delete_message	🗑️ Remova uma ou várias mensagens
get_messages	📜 Recupere o histórico de mensagens com opções avançadas de filtro

🔍 Pesquisa e Navegação

Ferramenta	Descrição
search_dialogs	🔎 Encontre usuários, grupos e canais por nome ou nome de usuário
message_from_link	🔗 Acesse mensagens específicas usando links do Telegram

📝 Gerenciamento de Rascunhos

Ferramenta	Descrição
get_draft	📋 Visualize o rascunho atual de qualquer conversa
set_draft	✍️ Crie ou limpe rascunhos de mensagens

📂 Manipulação de Mídia

Ferramenta	Descrição
media_download	📸 Baixe fotos, vídeos e documentos de mensagens

[!Note] Para informações detalhadas sobre parâmetros e exemplos de uso, execute mcp-telegram tools no seu terminal.

🛠️ Solução de Problemas

Erros de Banco de Dados Bloqueado

Executar várias instâncias do mcp-telegram usando o mesmo arquivo de sessão pode causar erros de database is locked devido ao armazenamento de sessão SQLite do Telethon. Certifique-se de que apenas uma instância use um arquivo de sessão por vez.

Forçando a Interrupção de Processos Existentes

Se você precisar interromper processos potencialmente travados:

• macOS / Linux: pkill -f "mcp-telegram"
• Windows: taskkill /F /IM mcp-telegram.exe /T (Verifique o Gerenciador de Tarefas para o nome exato do processo)

🤝 Contribuindo

Aceitamos contribuições! Se você quiser ajudar a melhorar o MCP Telegram, sinta-se à vontade para enviar issues, solicitações de recursos ou pull requests. Seus comentários e contribuições ajudam a tornar este projeto melhor para todos.

📝 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

---