MTM - MCP Telegram MORE

Canal de Telegram personalizado para Claude Code: un daemon + servidor MCP + MiniApp que convierte un bot de Telegram en un control remoto con todas las funciones para tus sesiones de Claude.

Características

Chat remoto con Claude

• Envía mensajes a Claude desde cualquier cliente de Telegram; las respuestas de Claude se transmiten de la misma manera.

• Archivos adjuntos compatibles en ambas direcciones (subidas / capturas de pantalla / descargas).

• MiniApp dentro del bot con tres pestañas: Chat, Tareas, Estado.

Aprobaciones de herramientas a través de Telegram

• Cada llamada a una herramienta de riesgo (Bash, Edit, Write, herramientas MCP, etc.) puede requerir aprobación explícita.

• Las solicitudes de aprobación llegan como mensajes de Telegram con botones de Permitir/Denegar; apruebas desde tu teléfono.

• La lista de permitidos a nivel de herramienta te permite aprobar automáticamente herramientas seguras (/allow Read, /deny Bash sudo).

• El modo YOLO global (/yolo on) desactiva temporalmente las aprobaciones.

Seguimiento de tareas en vivo

• La lista TodoWrite de Claude se refleja en la pestaña Tareas en tiempo real.

• Las transiciones de estado (pendiente → en_progreso → completado) se actualizan en vivo a través de WebSocket.

Visibilidad de subagentes y herramientas

• Barra de estado fija en la parte superior de la MiniApp que muestra lo que Claude está haciendo en este momento ("main: Edit · config.ts", "main + 2 subagentes ejecutándose").

• Burbujas de agente plegables para cada subagente generado: profundiza en las herramientas que ejecutó cada subagente.

• Las herramientas importantes (acciones de escritura, Task, MCP) están resaltadas; las herramientas de solo lectura están contraídas de forma predeterminada.

• El historial de eventos de herramientas se conserva durante 7 días de forma predeterminada (configurable).

Conciencia del espacio de trabajo

• Múltiples sesiones simultáneas de Claude en diferentes proyectos, cada una asignada a su propio espacio de trabajo.

• El comando /ws en el bot cambia el espacio de trabajo al que se dirigen los mensajes entrantes.

Control de acceso

• Flujo de emparejamiento: envía un mensaje directo al bot → recibe un código de 6 dígitos → canjea con /mcp-telegram:access pair <code>.

• Lista de permitidos con roles owner/user; el owner puede promover y eliminar.

• Modos de política: pairing (solo código), allowlist (cerrado), open (cualquiera — solo para desarrollo).

Abstracción de túnel

• URL pública expuesta a través de un proveedor de túnel conectable.

• La URL predeterminada se envía automáticamente a Telegram como el botón MiniApp del bot, incluyendo anulaciones por chat para cada usuario en la lista de permitidos.

Related MCP server: Straight Connect

Requisitos previos

• Bun — curl -fsSL https://bun.sh/install | bash

• Una herramienta de túnel que coincida con tu proveedor elegido:

  • cloudflared — instalar (predeterminado)

  • tuna — instalar (alternativo)

  • O trae tu propia URL a través del modo manual

• Un token de bot de Telegram de @BotFather (usa /newbot).

• Node.js (para los scripts de enlace de Claude Code: cualquier versión reciente).

Inicio rápido

# 1. Clone & install workspace deps
git clone <repo> mcp-telegram && cd mcp-telegram
bun install

# 2. Put the bot token into the daemon's env file
mkdir -p ~/.mcp-tg
echo "TELEGRAM_BOT_TOKEN=<your-bot-token>" > ~/.mcp-tg/.env

# 3. Build the MiniApp (served statically by the daemon)
bun run --cwd packages/miniapp build

# 4. Start the daemon (long-running; keep in a terminal or use install-service)
bun run --cwd packages/daemon start
# Logs print the public tunnel URL and port 17080.

# 5. Load the plugin into Claude Code (for hook + MCP integration)
claude --dangerously-load-development-channels plugin:mcp-telegram@mcp-telegram-local

# 6. From inside Claude Code, configure and pair
/mcp-telegram:configure <BOT_TOKEN>
# DM your bot in Telegram → receive a 6-digit pair code
/mcp-telegram:access pair ABC123

# 7. Open the MiniApp by tapping the "Open" button in the bot chat.

Configuración

~/.mcp-tg/.env (requerido)

Las variables son leídas desde ~/.mcp-tg/.env por el daemon al inicio; también puedes exportarlas en tu shell.

~/.mcp-tg/config.json (gestionado por el daemon)

Gestionado por el daemon y la habilidad /mcp-telegram:configure. Claves:

• tunnel_provider — uno de cloudflared | tuna | manual | none.

• tunnel_manual_url — solo se usa cuando tunnel_provider = manual; debe ser una URL HTTPS accesible públicamente que actúe como proxy hacia 127.0.0.1:17080.

• default_workspace — slug opcional utilizado para transmisiones de eventos del sistema antes de que se conecte cualquier espacio de trabajo.

Elección de un proveedor de túnel

# Default: cloudflared (auto-generated trycloudflare URL, rotates per restart)
/mcp-telegram:configure tunnel cloudflared

# tuna.am alternative
/mcp-telegram:configure tunnel tuna

# Bring-your-own public URL (nginx, frp, your domain, etc.)
/mcp-telegram:configure tunnel manual
# then edit ~/.mcp-tg/config.json and set tunnel_manual_url to your HTTPS endpoint.

# No public access (local MiniApp only; Telegram bot still works for chat)
/mcp-telegram:configure tunnel none

Después de cambiar de proveedor, reinicia el daemon. La nueva URL se envía al bot de Telegram automáticamente, tanto como el botón predeterminado de la MiniApp como para la anulación por chat de cada usuario en la lista de permitidos.

Comandos de barra diagonal (en Claude Code)

Todas las habilidades se comunican con el daemon en ejecución en http://127.0.0.1:17080/admin/* utilizando el token de portador en ~/.mcp-tg/admin.token (generado automáticamente en el primer arranque, modo 0600).

Comandos de bot (en Telegram)

Fuera de banda: envía cualquier texto que no sea un comando por mensaje directo para enviarlo a la sesión de Claude del espacio de trabajo seleccionado actualmente.

Despliegue

Para un uso ad-hoc, bun run --cwd packages/daemon start en una terminal es suficiente. Para cualquier cosa persistente:

# Linux — systemd user service (starts at login, restarts on failure)
/mcp-telegram:install-service

# Logs: journalctl --user -u mcp-telegram -f
# Stop: systemctl --user stop mcp-telegram
# Disable: systemctl --user disable mcp-telegram

En macOS / Windows, ejecuta el daemon bajo tu propio gestor de procesos (launchd, pm2, nssm, etc.); el MVP no incluye scripts de instalación para esas plataformas.

Arquitectura (breve)

• daemon (packages/daemon) — el único proceso de larga duración. Posee el bot, servidores HTTP + WS, SQLite, túnel y estado de aprobaciones.

• mcp-server (packages/mcp-server) — un proceso stdio generado por sesión de Claude Code; cliente WebSocket ligero del daemon.

• miniapp (packages/miniapp) — SPA de React construida una vez, servida estáticamente por el daemon en la URL del túnel.

• shared (packages/shared) — tipos de protocolo, estado y eventos de herramientas.

• plugin (plugin/) — plugin de Claude Code con configuración de servidor MCP, enlaces de aprobación, enlace de sincronización TodoWrite y el enlace de eventos de herramientas de subagente.

Los documentos de diseño completos se encuentran en docs/superpowers/specs/.

Pruebas

bun test                          # all workspaces
bun test --cwd packages/daemon    # daemon-only
bun test --cwd packages/miniapp   # MiniApp (vitest)

Seguridad

• Los códigos de emparejamiento están solo en memoria: un reinicio del daemon los invalida; envía un mensaje directo al bot para obtener un código nuevo.

• Nunca apruebes una solicitud de emparejamiento que llegó a través del propio bot. La habilidad /mcp-telegram:access rechaza operaciones posteriores a la entrada de Telegram para evitar la inyección de prompts a través de mensajes.

• initData de la MiniApp se valida en el lado del servidor (HMAC-SHA256 según la especificación de Telegram). Los JWT de la MiniApp duran 15 minutos.

• El daemon se vincula a 127.0.0.1; el alcance público existe solo a través del proveedor de túnel.

• MCP_TG_HOOK_TOKEN es la única credencial requerida por los enlaces; permanece dentro de ~/.mcp-tg/.env (modo 0600) y nunca se envía fuera de 127.0.0.1.

• El historial de eventos de herramientas se recorta después de MCP_TG_TOOL_EVENTS_TTL_DAYS (predeterminado 7); el índice agent_sessions se mantiene indefinidamente como un registro de auditoría compacto.