Telegram Notifier (Botfather)

Use o bot do Botfather para notificar você no Telegram.

Documentação

Servidor MCP Telegram Notifier (Botfather)

Um servidor MCP que permite a um LLM enviar mensagens e arquivos a um usuário por meio de um bot do Telegram, além de ler mensagens recebidas. Sem bibliotecas HTTP ou Telegram externas — apenas a API nativa fetch e o SDK oficial do MCP.

Início Rápido

Não é necessário clonar ou compilar — basta adicionar a configuração ao seu cliente MCP.

1. Criar um Bot do Telegram

Abra o Telegram e envie uma mensagem para @BotFather
Envie /newbot e siga as instruções para nomear seu bot
Copie o token do bot que você receber (ex.: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Encontrar Seu Chat ID

Envie qualquer mensagem para o seu novo bot no Telegram
Abra a seguinte URL no seu navegador, substituindo YOUR_BOT_TOKEN pelo seu token real:
```
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
```
Na resposta JSON, encontre "chat":{"id": 123456789} — esse número é o seu chat ID

Dica: Para chats em grupo, adicione o bot ao grupo, envie uma mensagem e verifique a mesma URL. Os IDs de chats em grupo são números negativos (ex.: -1001234567890).

3. Adicionar ao Seu Cliente MCP

Claude Desktop

Adicione isto ao arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "npx",
      "args": ["telegram-notifier-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

Claude Code

Adicione ao .mcp.json ou ~/.claude.json do seu projeto:

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "npx",
      "args": ["telegram-notifier-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

Codex CLI

Você pode configurar o Codex CLI de qualquer uma destas formas:

Opção A: Adicionar manualmente em ~/.codex/config.toml

[mcp_servers.telegram-notifier]
command = "npx"
args = ["telegram-notifier-mcp"]

[mcp_servers.telegram-notifier.env]
TELEGRAM_BOT_TOKEN = "your-bot-token-here"
TELEGRAM_CHAT_ID = "your-chat-id-here"

Opção B: Adicionar com um comando CLI

codex mcp add telegram-notifier \
  --env TELEGRAM_BOT_TOKEN=your-bot-token-here \
  --env TELEGRAM_CHAT_ID=your-chat-id-here \
  -- npx telegram-notifier-mcp

Pronto — seu LLM agora pode enviar notificações do Telegram para você.

Configuração

O servidor usa duas variáveis de ambiente:

Variável	Obrigatória	Descrição
`TELEGRAM_BOT_TOKEN`	Sim	Token do bot do @BotFather
`TELEGRAM_CHAT_ID`	Não	Chat ID padrão. Pode ser substituído por chamada de ferramenta via parâmetro `chatId`.

O servidor será encerrado com erro se TELEGRAM_BOT_TOKEN não estiver definido. Se TELEGRAM_CHAT_ID não estiver definido, você deve passar chatId em todas as chamadas de ferramenta.

Ferramentas

`send_message`

Envia uma mensagem de texto para um chat do Telegram.

Parâmetro	Tipo	Obrigatório	Descrição
`text`	string	Sim	O texto da mensagem a ser enviado
`chatId`	string	Não	Chat ID de destino (substitui `TELEGRAM_CHAT_ID`)
`parseMode`	string	Não	`Markdown`, `MarkdownV2` ou `HTML`
`disableNotification`	boolean	Não	Enviar silenciosamente, sem som de notificação

`send_document`

Envia um arquivo/documento para um chat do Telegram.

Parâmetro	Tipo	Obrigatório	Descrição
`filePath`	string	Sim	Caminho absoluto para o arquivo
`chatId`	string	Não	Chat ID de destino (substitui `TELEGRAM_CHAT_ID`)
`caption`	string	Não	Legenda para o documento
`parseMode`	string	Não	`Markdown`, `MarkdownV2` ou `HTML`
`disableNotification`	boolean	Não	Enviar silenciosamente, sem som de notificação

`send_photo`

Envia uma foto/imagem para um chat do Telegram.

Parâmetro	Tipo	Obrigatório	Descrição
`filePath`	string	Sim	Caminho absoluto para o arquivo de imagem
`chatId`	string	Não	Chat ID de destino (substitui `TELEGRAM_CHAT_ID`)
`caption`	string	Não	Legenda para a foto
`parseMode`	string	Não	`Markdown`, `MarkdownV2` ou `HTML`
`disableNotification`	boolean	Não	Enviar silenciosamente, sem som de notificação

`send_video`

Envia um vídeo para um chat do Telegram.

Parâmetro	Tipo	Obrigatório	Descrição
`filePath`	string	Sim	Caminho absoluto para o arquivo de vídeo
`chatId`	string	Não	Chat ID de destino (substitui `TELEGRAM_CHAT_ID`)
`caption`	string	Não	Legenda para o vídeo
`parseMode`	string	Não	`Markdown`, `MarkdownV2` ou `HTML`
`disableNotification`	boolean	Não	Enviar silenciosamente, sem som de notificação

`send_audio`

Envia um arquivo de áudio para um chat do Telegram.

Parâmetro	Tipo	Obrigatório	Descrição
`filePath`	string	Sim	Caminho absoluto para o arquivo de áudio
`chatId`	string	Não	Chat ID de destino (substitui `TELEGRAM_CHAT_ID`)
`caption`	string	Não	Legenda para o áudio
`parseMode`	string	Não	`Markdown`, `MarkdownV2` ou `HTML`
`disableNotification`	boolean	Não	Enviar silenciosamente, sem som de notificação

`get_updates`

Verifica se há novas mensagens enviadas ao bot. Retorna apenas mensagens recebidas desde a última verificação.

Parâmetro	Tipo	Obrigatório	Descrição
`limit`	number	Não	Máximo de mensagens a recuperar (1-100, padrão 10)
`timeout`	number	Não	Tempo limite de long-polling em segundos (0-30, padrão 0). Defina >0 para aguardar novas mensagens.

Downloads de Arquivos

Quando uma mensagem contém mídia (foto, documento, vídeo, áudio, mensagem de voz ou adesivo), o servidor baixa automaticamente o arquivo para ~/.telegram-notifier-mcp/downloads/ e inclui o caminho local na saída. Isso permite que o LLM leia ou processe o arquivo diretamente.

Os arquivos são salvos como <timestamp>-<original_filename> para evitar colisões
As fotos são baixadas na maior resolução disponível
A API do Bot do Telegram limita downloads a 20 MB
Se um download falhar, a saída volta a apenas rotular o tipo de mídia

Testando com o MCP Inspector

Você pode testar o servidor interativamente usando o MCP Inspector:

TELEGRAM_BOT_TOKEN="your-token" TELEGRAM_CHAT_ID="your-chat-id" \
  npx @modelcontextprotocol/inspector npx telegram-notifier-mcp

Isso abre uma interface no navegador onde você pode invocar cada ferramenta e ver os resultados.

Tratamento de Erros

O servidor trata erros de forma graciosa e retorna mensagens descritivas:

Cenário	Comportamento
`TELEGRAM_BOT_TOKEN` ausente	O servidor é encerrado na inicialização com instruções
Chat ID ausente (sem variável de ambiente, sem parâmetro)	Retorna `isError: true` com mensagem
Arquivo não encontrado	Retorna `isError: true` com o caminho do arquivo
Arquivo excede 50 MB	Retorna `isError: true` com o tamanho do arquivo
Erro da API do Telegram	Retorna `isError: true` com a descrição do erro do Telegram

Todos os logs do servidor vão para stderr para nunca interferirem no transporte MCP stdio em stdout.

Limites de Tamanho de Arquivo

O Telegram impõe um limite de 50 MB para uploads de arquivos via API do Bot. O servidor valida o tamanho do arquivo antes do upload e retorna um erro se o limite for excedido.

Desenvolvimento

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

# Watch mode — rebuilds on file changes
npm run dev

Publicação

As versões são publicadas no npm automaticamente via GitHub Actions quando você cria uma release no GitHub.

Configuração:

Adicione seu token npm como um segredo do repositório chamado NPM_TOKEN em GitHub Settings > Secrets and variables > Actions
Atualize a versão em package.json
Crie uma nova release no GitHub — o workflow compilará e publicará no npm

Licença

MIT