mcp-telegram-bridge

Puente MCP Stdio hacia la API de Telegram Bot con depuración y lista de permitidos de chats.

Documentación

mcp-telegram-bridge

Puente controlado para canales de Telegram para cualquier host MCP.

Un pequeño servidor stdio Model Context Protocol que se sitúa entre tu agente local (Cursor, Claude Desktop, Windsurf, agentes Grok/Cursor y otros) y la API de Bot de Telegram. El agente posee la lógica de conversación; este proceso maneja E/S, limpieza de salida siempre activa y aplicación de la lista de permitidos del chat. La clasificación estricta de entrada es opcional y está deshabilitada por defecto.

Diseñado para despliegues propiedad del cliente: el puente se ejecuta en tu máquina, no en una VM de Grok alojada. Los flujos de juegos y de máster de juego son un caso de demostración, no el producto.

Contexto del propietario: Antonio Castellon / Castellon.CH - arquitecto independiente suizo. La misma forma de puente es útil para patrones de laboratorio en PYME (canales de notificación, traspaso de especialistas, borradores moderados) junto a conectores de correo electrónico o ERP.

Qué / por qué

Los agentes son buenos razonando y malos manteniendo una sesión cruda de la API de Bot por sí mismos. Telegram es una superficie humana conveniente (grupos, botones, móvil). Este proyecto te da un puente estrecho y revisable:

Propiedad del cliente - stdio MCP en la estación de trabajo o runner de CI que ya aloja tu agente.
Independiente del host - cualquier cliente MCP que pueda lanzar un comando local.
Controlado - limpieza de salida y ALLOWED_CHAT_IDS opcional; clasificación estricta de entrada opcional para grupos no confiables.
Herramientas mínimas - enviar, editar markup, responder callbacks, obtener actualizaciones, getMe / getChat. Sin motor de juego, sin archivo de bandeja de entrada, sin wake-RPC.

Patrón de propuesta para PYME: comienza con un canal de notificación o triaje de Telegram usando la misma arquitectura que luego aplicarías a correo electrónico o ERP.

Arquitectura

  +---------------------------+
  |  MCP host / agents        |  Cursor / Claude Desktop / Windsurf / ...
  |  (conversation logic)     |
  +-------------+-------------+
                |
                |  MCP (stdio)
                v
  +---------------------------+
  |  mcp-telegram-bridge      |  tools + safety scrub/classify
  |  (this process)           |
  +-------------+-------------+
                |
                |  HTTPS Bot API
                v
  +---------------------------+
  |  api.telegram.org         |
  +-------------+-------------+
                v
         Telegram chats / groups

El agente posee los offsets de sondeo, los traspasos entre especialistas y la política de producto. Este servidor aplica controles de destino y envía texto limpiado; la clasificación de entrada es opcional.

Instalación

Requisitos: Python 3.11+, un token de bot de Telegram de @BotFather.

git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
cd mcp-telegram-bridge
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env        # set TELEGRAM_BOT_TOKEN (never commit .env)

O sin clonar, una vez publicado:

uvx --from mcp-telegram-bridge mcp-telegram-bridge
# or: pipx run mcp-telegram-bridge

Cursor / Claude Desktop (`mcp.json`)

Ejemplo para Cursor (configuración de MCP de usuario) o Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram-bridge": {
      "command": "uvx",
      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "ALLOWED_CHAT_IDS": "-1001234567890"
      }
    }
  }
}

En Windows, apunta command al Python de tu venv si es necesario, por ejemplo:

C:\DEV.Personal\mcp-telegram-bridge\.venv\Scripts\python.exe

Deja ALLOWED_CHAT_IDS vacío solo si aceptas intencionalmente tráfico de cada chat que el bot pueda ver - documenta ese riesgo para tu despliegue.

Prueba rápida sin host:

python -m mcp_telegram_bridge
# process waits on stdio for MCP JSON-RPC (Ctrl+C to stop)

Herramientas MCP

Herramienta	Propósito
`telegram_get_me`	Verificación de identidad / conectividad del bot
`telegram_send_message`	`chat_id`, `text`, `parse_mode` opcional, `buttons=[{id,label}]` opcional
`telegram_edit_reply_markup`	Eliminar o reemplazar botones en línea
`telegram_answer_callback`	Confirmar un `callback_query_id` (toast opcional)
`telegram_get_updates`	`offset`, `limit`, `timeout` - devuelve mensajes + callback_queries; el agente posee el bucle
`telegram_get_chat`	Metadatos del chat

El texto de salida siempre se limpia. ALLOWED_CHAT_IDS restringe destinos cuando está configurado. telegram_get_updates ejecuta el clasificador heurístico de secretos/NSFW solo cuando SAFETY_STRICT=1 (o true/yes/on); el modo estricto es opcional y recomendado para grupos públicos o no confiables.

Guía de uso

Agentes colaborativos en un grupo de Telegram

Ejecuta un proceso de puente por bot (o un bot con roles de agente claros). Usa el grupo para notas de standup, colas de triaje y traspaso entre agentes especialistas ("ops confirma; facturación redacta la respuesta"). Mantén a los humanos en el bucle para acciones irreversibles.

Máster de juego / facilitador de mesa (demo)

Envía texto de escena con buttons=[{id,label}, ...] para elecciones de jugadores; en callback_query, responde al callback, opcionalmente maneja el primer toque estilo claim en el agente, luego edita el markup para limpiar elecciones gastadas. Esto es una demo de botones + bucle de agente - no un motor de RPG incluido.

Canal de notificación de soporte / operaciones

Empuja alertas con botones de confirmación (ack, snooze, escalate). El agente registra quién tocó qué; Telegram es la superficie de pager, no la fuente de verdad.

Asistente de moderación comunitaria

Redacta respuestas y sugiere acciones. Los humanos aún poseen ban / restricción / eliminación en el Administrador de Telegram - indícalo en el prompt de tu agente. El puente no debe tratarse como autoridad de moderación.

Patrón de laboratorio / PYME

Misma forma que un conector de correo electrónico o ERP: herramientas estrechas, destinos en lista de permitidos, salida limpiada, advertencias de entrada explícitas. Telegram es el canal de demostración; cambia el transporte después sin reescribir la política del agente.

Lo que esto NO es

No es un SaaS de bot alojado ni un puente en la nube multiinquilino
No es solo para Grok (funciona con cualquier host stdio MCP)
No es un motor completo de RPG / juego (sin reglas de dados, sin base de datos de campaña en este repositorio)
No es un bot administrador sin supervisión (sin herramientas de ban incluidas aquí)

Relación con demos hermanas

Contexto opcional solamente - este proyecto no las requiere:

grokgame - superficie de demo de mesa / juego
grok2telegram - experimento de puente anterior cuya doctrina de seguridad informó SAFETY.md y safety.py

mcp-telegram-bridge es la extracción reutilizable e independiente del host: E/S + seguridad, sin bucle de juego y sin lógica de wake de VM Grok.

Seguridad

Consulta SAFETY.md para el modelo de amenazas, limpieza siempre activa y controles de lista de permitidos, manejo de tokens y modo estricto opcional. No pongas secretos en el repositorio; prefiere ALLOWED_CHAT_IDS en configuraciones tipo producción.

Desarrollo

pip install -e ".[dev]"
pytest

Las pruebas simulan HTTP de Telegram con respx / httpx; no se requiere token en vivo.

Registro MCP

Nombre canónico: io.github.antonio-castellon/mcp-telegram-bridge

Licencia

MIT (c) Antonio Castellon / Castellon.CH

mcp-telegram-bridge

Documentación