Telegram Notify MCP

Telegram Notify MCP

Un servidor MCP extremadamente simple con un solo propósito: enviarte el progreso de tus agentes de IA de vuelta a Telegram.

Eso es todo. Sin gestión de chats, sin administración de grupos, sin consultas en línea. Solo notificaciones — como texto, imágenes o archivos.

Inicias un agente, te alejas, y recibes un mensaje de Telegram cuando termina (o mientras está trabajando). Nada más, nada menos.

Inicio Rápido

1. Crea un Bot de Telegram

1. Envía un mensaje a @BotFather en Telegram
2. Envía /newbot y sigue las instrucciones
3. Copia el token del bot

2. Inicia un chat con tu bot

Encuentra tu bot en Telegram y envía /start. Esto es necesario para que el bot pueda descubrir tu ID de chat.

3. Añádelo a tu 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

Añade esto a tu archivo de configuración de MCP:

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

Configuración

Variable de Entorno	Requerida	Descripción
TELEGRAM_BOT_TOKEN	Sí	Token del bot de @BotFather
TELEGRAM_USERNAME	Sí	Tu nombre de usuario de Telegram (sin el @)

Herramientas

Tres herramientas. Esa es toda la superficie.

send_message

Envía una actualización de texto al usuario.

Parámetro	Tipo	Requerido	Descripción
text	string	Sí	El texto del mensaje
parse_mode	string	No	HTML, Markdown, o MarkdownV2

send_photo

Envía una imagen — una captura de pantalla, un gráfico, un visual generado.

Parámetro	Tipo	Requerido	Descripción
photo	string	Sí	URL o ruta de archivo absoluta
caption	string	No	Pie de foto
parse_mode	string	No	Modo de formato del pie de foto

send_document

Envía un archivo — un informe, un registro, un artefacto de compilación.

Parámetro	Tipo	Requerido	Descripción
document	string	Sí	URL o ruta de archivo absoluta
caption	string	No	Pie de documento
parse_mode	string	No	Modo de formato del pie de documento

Cómo Funciona

• En la primera llamada a la herramienta, el servidor resuelve tu nombre de usuario a un ID de chat mediante el getUpdates de la API de Bot de Telegram
• Enviar /start al bot es necesario — los bots de Telegram solo pueden enviar mensajes a usuarios que han iniciado una conversación
• El ID de chat se almacena en caché durante la vida del proceso

Desarrollo

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

Licencia

MIT