Telegram Notify MCP

Telegram Notify MCP

Um servidor MCP extremamente simples com uma única função: enviar o progresso do seu agente de IA de volta para você no Telegram.

É isso. Sem gerenciamento de chat, sem administração de grupos, sem consultas inline. Apenas notificações — como texto, imagens ou arquivos.

Você inicia um agente, se afasta e recebe uma mensagem no Telegram quando ele terminar (ou enquanto estiver trabalhando). Nada mais, nada menos.

Início Rápido

1. Crie um Bot no Telegram

1. Envie uma mensagem para @BotFather no Telegram
2. Envie /newbot e siga as instruções
3. Copie o token do bot

2. Inicie uma conversa com seu bot

Encontre seu bot no Telegram e envie /start. Isso é necessário para que o bot possa descobrir seu ID de chat.

3. Adicione ao seu cliente MCP

Claude Code

claude mcp add telegram -e TELEGRAM_BOT_TOKEN=your-token -e TELEGRAM_USERNAME=your-username -- npx @parthj/telegram-notify-mcp

Claude Desktop / Cursor / Windsurf

Adicione ao seu arquivo de configuração MCP:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@parthj/telegram-notify-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_USERNAME": "your-telegram-username"
      }
    }
  }
}

Configuração

Variável de Ambiente	Obrigatória	Descrição
TELEGRAM_BOT_TOKEN	Sim	Token do bot obtido com @BotFather
TELEGRAM_USERNAME	Sim	Seu nome de usuário no Telegram (sem o @)

Ferramentas

Três ferramentas. Essa é toda a superfície de uso.

send_message

Envie uma atualização de texto para o usuário.

Parâmetro	Tipo	Obrigatório	Descrição
text	string	Sim	O texto da mensagem
parse_mode	string	Não	HTML, Markdown ou MarkdownV2

send_photo

Envie uma imagem — uma captura de tela, um gráfico, um visual gerado.

Parâmetro	Tipo	Obrigatório	Descrição
photo	string	Sim	URL ou caminho absoluto do arquivo
caption	string	Não	Legenda da foto
parse_mode	string	Não	Modo de formatação da legenda

send_document

Envie um arquivo — um relatório, um log, um artefato de build.

Parâmetro	Tipo	Obrigatório	Descrição
document	string	Sim	URL ou caminho absoluto do arquivo
caption	string	Não	Legenda do documento
parse_mode	string	Não	Modo de formatação da legenda

Como Funciona

• Na primeira chamada de ferramenta, o servidor resolve seu nome de usuário para um ID de chat via getUpdates da API do Telegram Bot
• Enviar /start para o bot é obrigatório — bots do Telegram só podem enviar mensagens para usuários que iniciaram uma conversa
• O ID de chat é armazenado em cache durante toda a vida útil do processo

Desenvolvimento

git clone https://github.com/ParthJadhav/telegram-notify-mcp.git
cd telegram-notify-mcp
npm install
npm run build

Licença

MIT