telegram-bot-mcp

Un servidor MCP que permite a Claude gestionar un canal de Telegram a través de la API de Telegram Bot: realiza un seguimiento del crecimiento de suscriptores día a día, y publica, edita, fija o elimina publicaciones.

🇮🇷 راهنمای فارسی · Guía de implementación · راهنمای دپلوی

Qué es esto

La API de Telegram Bot es una API HTTPS simple. Este repositorio la envuelve en el Protocolo de Contexto de Modelo para que un asistente de IA pueda invocarla como herramientas — "¿cómo le fue al canal esta semana?" en lugar de curl https://api.telegram.org/bot.../getChatMemberCount.

Se distribuye en dos formatos, a partir de las mismas definiciones de herramientas:

Elige el servidor remoto si quieres informes diarios que se ejecuten sin ti. Elige el plugin si solo usas Claude Code y prefieres que nada salga de tu máquina.

Herramientas

Ambas versiones exponen las mismas ocho herramientas.

Inicio rápido (servidor remoto)

1. Crea un bot con @BotFather → /newbot → copia el token.

2. Añade el bot como administrador de tu canal.

3. Crea un val HTTP en val.town y pega el contenido de remote/telegram-mcp.ts.

4. Establece tres variables de entorno en la barra lateral del val: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.

5. En Claude: Configuración → Conectores → Añadir conector personalizado → https://<tu-val>.web.val.run/mcp → introduce tu contraseña.

Guía completa, incluida la ruta del plugin local y la resolución de problemas: docs/deployment.md.

Seguridad

No se incluye ninguna credencial en este repositorio. config.json y .env están en .gitignore; solo se rastrean los archivos .example. Antes de hacer push de cualquier fork, confirma con git status que ninguno de los dos aparece.

El servidor remoto implementa un flujo completo de autorización OAuth 2.1 en lugar de quedar abierto en internet:

• Las solicitudes sin un token válido reciben un 401 con una cabecera WWW-Authenticate que apunta a los metadatos del recurso, según RFC 9728.

• Los clientes se registran dinámicamente (RFC 7591); no se distribuyen secretos de cliente.

• Los códigos de autorización están protegidos con PKCE (S256) y los URI de redirección se validan contra el conjunto registrado.

• Los tokens de acceso y de actualización están firmados con HMAC-SHA256 y no tienen estado: acceso de 24 horas, actualización de 30 días.

• La pantalla de consentimiento está protegida por MCP_PASSWORD, que tú eliges.

Tu token de bot permanece en las variables de entorno del host y nunca lo devuelve ninguna herramienta.

Trata MCP_PASSWORD como una contraseña para tu canal. Cualquiera que la tenga puede conectarse y publicar mensajes.

Limitaciones

La API de Bot informa solo del número de suscriptores. Las vistas de las publicaciones, los reenvíos y las estadísticas oficiales del canal no están expuestos a los bots — requieren un cliente MTProto con una cuenta de usuario que administre el canal.

Un bot generalmente solo puede editar mensajes que él mismo haya enviado. Telegram define el derecho de administrador can_edit_messages ("puede editar mensajes de otros usuarios; solo para canales"), pero el comportamiento del bot con publicaciones de administradores humanos no está claramente documentado — pruébalo en tu propio canal antes de confiar en ello. La eliminación es diferente: can_delete_messages cubre explícitamente los mensajes de otros usuarios.

La comparación de crecimiento requiere que el historial sobreviva entre ejecuciones. En Val Town eso es el almacenamiento de blobs, que persiste. En el plugin local es un archivo CSV — guárdalo en un lugar duradero, no en un directorio temporal.

Estructura del repositorio

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

Pruebas

npm test

Requiere Node 22.6+. Veintidós comprobaciones cubren el flujo de OAuth (desafío 401, documentos de descubrimiento, registro dinámico, rechazo de PKCE, concesión de tokens y rechazo de tokens falsificados) y el protocolo MCP (inicialización, notificaciones, listado de herramientas, aritmética de delta de crecimiento, rutas de error de herramientas). La API de Telegram está simulada; no se necesita acceso a la red ni un token de bot real.

La suite se ejecuta contra el código fuente implementado — tests/build.mjs reescribe exactamente una línea, la importación del blob de Val Town, y no cambia nada más.

Licencia

MIT