Telegram Notifier (Botfather)

Usa el bot de Botfather para notificarte en Telegram.

Documentación

Servidor MCP de Telegram Notifier

Un servidor MCP que permite a un LLM enviar mensajes y archivos a un usuario a través de un bot de Telegram, y leer mensajes entrantes. Sin bibliotecas HTTP o de Telegram externas — solo la API nativa de fetch y el SDK oficial de MCP.

Inicio Rápido

No se requiere clonar ni compilar — solo añade la configuración a tu cliente MCP.

1. Crear un Bot de Telegram

Abre Telegram y envía un mensaje a @BotFather
Envía /newbot y sigue las instrucciones para nombrar tu bot
Copia el token del bot que recibas (por ejemplo, 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Encuentra tu ID de Chat

Envía cualquier mensaje a tu nuevo bot en Telegram
Abre la siguiente URL en tu navegador, reemplazando YOUR_BOT_TOKEN con tu token real:
```
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
```
En la respuesta JSON, busca "chat":{"id": 123456789} — ese número es tu ID de chat

Consejo: Para chats de grupo, añade el bot al grupo, envía un mensaje y revisa la misma URL. Los IDs de chats de grupo son números negativos (por ejemplo, -1001234567890).

3. Añadir a tu Cliente MCP

Claude Desktop

Añade esto a tu archivo de configuración de 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

Añade a .mcp.json o ~/.claude.json de tu proyecto:

{
  "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

Puedes configurar Codex CLI de cualquiera de estas formas:

Opción A: Añadirlo manualmente en ~/.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"

Opción B: Añadirlo con un 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

Eso es todo — tu LLM ahora puede enviarte notificaciones de Telegram.

Configuración

El servidor utiliza dos variables de entorno:

Variable	Requerida	Descripción
`TELEGRAM_BOT_TOKEN`	Sí	Token del bot de @BotFather
`TELEGRAM_CHAT_ID`	No	ID de chat predeterminado. Puede sobrescribirse por llamada de herramienta mediante el parámetro `chatId`.

El servidor saldrá con un error si TELEGRAM_BOT_TOKEN no está configurado. Si TELEGRAM_CHAT_ID no está configurado, debes pasar chatId a cada llamada de herramienta.

Herramientas

`send_message`

Envía un mensaje de texto a un chat de Telegram.

Parámetro	Tipo	Requerido	Descripción
`text`	string	Sí	El texto del mensaje a enviar
`chatId`	string	No	ID de chat de destino (sobrescribe `TELEGRAM_CHAT_ID`)
`parseMode`	string	No	`Markdown`, `MarkdownV2` o `HTML`
`disableNotification`	boolean	No	Enviar silenciosamente sin sonido de notificación

`send_document`

Envía un archivo/documento a un chat de Telegram.

Parámetro	Tipo	Requerido	Descripción
`filePath`	string	Sí	Ruta absoluta al archivo
`chatId`	string	No	ID de chat de destino (sobrescribe `TELEGRAM_CHAT_ID`)
`caption`	string	No	Leyenda para el documento
`parseMode`	string	No	`Markdown`, `MarkdownV2` o `HTML`
`disableNotification`	boolean	No	Enviar silenciosamente sin sonido de notificación

`send_photo`

Envía una foto/imagen a un chat de Telegram.

Parámetro	Tipo	Requerido	Descripción
`filePath`	string	Sí	Ruta absoluta al archivo de imagen
`chatId`	string	No	ID de chat de destino (sobrescribe `TELEGRAM_CHAT_ID`)
`caption`	string	No	Leyenda para la foto
`parseMode`	string	No	`Markdown`, `MarkdownV2` o `HTML`
`disableNotification`	boolean	No	Enviar silenciosamente sin sonido de notificación

`send_video`

Envía un video a un chat de Telegram.

Parámetro	Tipo	Requerido	Descripción
`filePath`	string	Sí	Ruta absoluta al archivo de video
`chatId`	string	No	ID de chat de destino (sobrescribe `TELEGRAM_CHAT_ID`)
`caption`	string	No	Leyenda para el video
`parseMode`	string	No	`Markdown`, `MarkdownV2` o `HTML`
`disableNotification`	boolean	No	Enviar silenciosamente sin sonido de notificación

`send_audio`

Envía un archivo de audio a un chat de Telegram.

Parámetro	Tipo	Requerido	Descripción
`filePath`	string	Sí	Ruta absoluta al archivo de audio
`chatId`	string	No	ID de chat de destino (sobrescribe `TELEGRAM_CHAT_ID`)
`caption`	string	No	Leyenda para el audio
`parseMode`	string	No	`Markdown`, `MarkdownV2` o `HTML`
`disableNotification`	boolean	No	Enviar silenciosamente sin sonido de notificación

`get_updates`

Comprueba si hay nuevos mensajes enviados al bot. Solo devuelve mensajes recibidos desde la última comprobación.

Parámetro	Tipo	Requerido	Descripción
`limit`	number	No	Máximo de mensajes a recuperar (1-100, predeterminado 10)
`timeout`	number	No	Tiempo de espera de polling largo en segundos (0-30, predeterminado 0). Establece >0 para esperar nuevos mensajes.

Descargas de Archivos

Cuando un mensaje contiene medios (foto, documento, video, audio, mensaje de voz o sticker), el servidor descarga automáticamente el archivo a ~/.telegram-notifier-mcp/downloads/ e incluye la ruta local en la salida. Esto permite que el LLM lea o procese el archivo directamente.

Los archivos se guardan como <timestamp>-<original_filename> para evitar colisiones
Las fotos se descargan en la resolución más alta disponible
La API de Bot de Telegram limita las descargas a 20 MB
Si una descarga falla, la salida se reduce a solo etiquetar el tipo de medio

Pruebas con el Inspector de MCP

Puedes probar el servidor de forma interactiva usando el Inspector de MCP:

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

Esto abre una interfaz de navegador donde puedes invocar cada herramienta y ver los resultados.

Manejo de Errores

El servidor maneja los errores de forma elegante y devuelve mensajes descriptivos:

Escenario	Comportamiento
Falta `TELEGRAM_BOT_TOKEN`	El servidor sale al inicio con instrucciones
Falta ID de chat (sin variable de entorno, sin parámetro)	Devuelve `isError: true` con mensaje
Archivo no encontrado	Devuelve `isError: true` con la ruta del archivo
Archivo supera 50 MB	Devuelve `isError: true` con el tamaño del archivo
Error de API de Telegram	Devuelve `isError: true` con la descripción del error de Telegram

Todos los registros del servidor van a stderr para que nunca interfieran con el transporte MCP stdio en stdout.

Límites de Tamaño de Archivo

Telegram impone un límite de 50 MB para subidas de archivos a través de la API de Bot. El servidor valida el tamaño del archivo antes de subirlo y devuelve un error si se excede el límite.

Desarrollo

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

Publicación

Las versiones se publican en npm automáticamente mediante GitHub Actions cuando creas una versión de GitHub.

Configuración:

Añade tu token de npm como secreto del repositorio llamado NPM_TOKEN en Configuración de GitHub > Secretos y variables > Acciones
Incrementa la versión en package.json
Crea una nueva versión de GitHub — el flujo de trabajo compilará y publicará en npm

Licencia

MIT