telegram-channel-mcp-server

Servidor MCP (stdio) para publicar y gestionar publicaciones en un canal de Telegram mediante la API de Bot. Permite que un agente (Claude Code, Claude Desktop, etc.) publique texto, fotos, vídeos, álbumes, documentos, mensajes de voz, notas de vídeo, encuestas/trivias y contenido de pago, y edite/elimine/fije publicaciones.

Instalación

npm install
npm run build

Related MCP server: Telegram Bot MCP Server

Configuración

Claude Code

claude mcp add telegram-channel -e TELEGRAM_BOT_TOKEN=123:ABC -e TELEGRAM_CHAT_ID=-1001234567890 -- node /abs/path/telegram-channel-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "telegram-channel": {
      "command": "node",
      "args": ["/abs/path/telegram-channel-mcp/dist/index.js"],
      "env": { "TELEGRAM_BOT_TOKEN": "123:ABC", "TELEGRAM_CHAT_ID": "-1001234567890" }
    }
  }
}

Herramientas

Multimedia en cada herramienta se proporciona como una cadena: una URL pública http(s), una ruta absoluta a un archivo local (el servidor lo sube) o un file_id de Telegram (devuelto en el resultado del envío, para que puedas reutilizar un archivo sin volver a subirlo).

Botones son una matriz de filas: [[{ "text": "Sitio web", "url": "https://…", "style": "primary" }], [{ "text": "Copiar", "copy_text": "PROMO" }]]. Exactamente uno de url / callback_data / copy_text; style: primary | success | danger.

Limitaciones de la API de Bot gestionadas por el servidor

• Los álbumes y las notas de vídeo no pueden llevar botones: envíalos en un mensaje aparte.

• En un álbum, show_caption_above_media se aplica a todos los elementos a la vez.

• El contenido de pago solo funciona en canales, de 1 a 10 000 estrellas.

• Las encuestas en canales siempre son anónimas.

• Límites: texto 4096 caracteres, pie de foto 1024, archivo 50 MB al subir / 20 MB mediante URL.

Desarrollo

npm run dev                        # run from sources
npm run smoke -- /path/to/img.png  # e2e check against a real channel (creates and deletes test posts)
npx @modelcontextprotocol/inspector node dist/index.js

Estructura: src/telegram.ts - cliente de API y resolución de multimedia, src/schemas.ts - esquemas zod compartidos, src/format.ts - formato de respuestas, src/tools/* - herramientas agrupadas por dominio, src/index.ts - punto de entrada.