Teleloom
Servidor MCP local de Telegram con múltiples cuentas y perfiles de bots, búsqueda de chats, resúmenes con fuentes, inspección de medios y acciones con vista previa y permisos limitados.
Documentación
Tu Telegram, listo para agentes.
Un kit de herramientas para Telegram con habilidades portables para agentes, un servidor MCP y una CLI.
Comenzar · Русский · Clientes · Tareas de ejemplo · Para agentes
Teleloom conecta tus cuentas y bots de Telegram al agente que ya usas. Encuentra mensajes entre chats, ponte al día en discusiones, crea resúmenes con enlaces a las fuentes, inspecciona documentos y prepara acciones que puedes revisar antes de que se ejecuten.
Un propietario local gestiona conexiones y estado. Varios clientes de agentes lo comparten; tú eliges los chats accesibles y los permisos para cada cuenta.
Lo que puedes hacer
| Tarea | Lo que Teleloom proporciona |
|---|---|
| Ponerse al día | Leer historial, buscar mensajes y autores, seguir respuestas y temas, revisar mensajes no leídos |
| Investigar muchos chats | Trabajos de recopilación limitados, originales congelados, contadores, extractos, exportaciones y brechas de cobertura explícitas |
| Escribir un resumen verificable | Referencias de evidencia estables, enlaces a fuentes, validación de afirmaciones/revisiones e instrucciones portables de resumen |
| Trabajar con medios | Fotos, texto enriquecido, documentos/PDF, OCR opcional y transcripción opcional |
| Actuar con control | Vista previa y confirmación de mensajes, respuestas, medios, transmisiones limitadas y cambios compatibles de cuenta/grupo |
| Mantener el contexto manejable | Selección de campos reutilizable, vistas compactas, presupuestos de salida y acceso a los originales exactos |
67 herramientas MCP y seis habilidades portables: conectar, leer, bandeja de entrada, resumen, enviar y transmitir. Consulta la referencia de herramientas para conocer los contratos y límites exactos.
Inicio rápido
Requiere Git, uv y Python 3.12–3.14. Las cuentas de usuario necesitan tu propio ID/hash de API de Telegram desde my.telegram.org. Los bots usan un token de bot. Las credenciales se ingresan localmente, fuera de una conversación de agente.
git clone --single-branch https://github.com/starsinc1708/teleloom.git
cd teleloom
uv sync --frozen
uv run teleloom init
uv run teleloom auth user --profile personal --ui browser
uv run teleloom profile list
En tu teléfono, abre Telegram → Configuración → Dispositivos → Vincular dispositivo de escritorio y escanea el código QR. Se requiere un almacén de credenciales del sistema operativo funcional para guardar la sesión. Para hosts sin interfaz gráfica, bots, restricciones de lectura y solución de problemas de primer uso, sigue la guía en inglés o la guía en ruso.
Conecta un cliente e instala sus habilidades:
uv run teleloom config client --client codex
uv run teleloom skills install --client codex
Fusiona el fragmento impreso en la configuración del cliente existente y luego vuelve a conectar
MCP. Usa claude, opencode (v2), opencode-v1, hermes o pi para otros clientes.
Las habilidades existentes se conservan a menos que solicites explícitamente su reemplazo.
Rutas de clientes y comprobaciones de descubrimiento.
Para OpenCode 2 o Hermes, registra MCP a través de la CLI del cliente instalado:
uv run teleloom config client --client opencode --install
uv run teleloom skills install --client opencode
uv run teleloom config client --client hermes --install
uv run teleloom skills install --client hermes
Elige el par para tu cliente y luego vuelve a conectar MCP (opencode reload para un
servicio de OpenCode en ejecución). --install está disponible en
el checkout actual del código fuente; v0.5.0 solo imprime fragmentos. Una conexión idéntica
se conserva; una entrada teleloom conflictiva requiere revisión manual. Las habilidades de Hermes
siguen hermes config path, incluido su perfil activo y HERMES_HOME.
Prueba esto primero:
Verifica el estado del servidor y lista los perfiles. Pídeme que seleccione un perfil y un chat. Lee sus últimos 20 mensajes sin marcarlos como leídos. Resume los temas principales con enlaces a los mensajes e indica cualquier contexto faltante. No envíes mensajes ni cambies configuraciones o permisos.
Control y privacidad
- Los nuevos perfiles pueden leer todos los chats accesibles para la cuenta. Usa la política de lectura seleccionada para restringir el acceso; la guía de configuración explica las compuertas independientes de herramientas y chats.
- El envío y otros cambios externos requieren sus propios permisos y una vista previa inmutable más confirmación. Una entrega incierta se registra como desconocida y nunca se reenvía automáticamente.
- Una instrucción humana explícita para enviar a destinatarios exactos puede autorizar ese
envío con vista previa y archivos locales seleccionados a través de
owner_authorized=true. Las listas de permitidos permanentes y las raíces de archivos permanecen sin cambios. Autorización de planes. - Las credenciales de Telegram permanecen en el llavero del sistema operativo o en el entorno proporcionado. El estado y las exportaciones permanecen en tu directorio de datos local. Tu proveedor de agente/modelo elegido recibe la evidencia que solicites; el análisis externo opcional es explícito.
- Leer no confirma mensajes. El historial de bots cubre observaciones recopiladas, y los resultados de búsqueda/resumen revelan su alcance y brechas.
La bandera de confirmación es una entrada confiable de tu cliente de agente; no es una prueba independiente de aprobación humana. Todos los clientes locales comparten un propietario del sistema operativo confiable. Modelo de seguridad y reporte de vulnerabilidades.
Clientes y características opcionales
| Cliente | Integración |
|---|---|
| Codex | Stdio MCP y seis habilidades portables |
| Claude Code | Stdio MCP y seis habilidades portables |
| OpenCode 2 / 1 | Configuración MCP nativa; objetivos de versión separados |
| Hermes | Configuración y habilidades nativas de mcp_servers |
| Pi | Configuración y habilidades nativas de mcpServers |
| Claude Desktop | Configuración MCP; el comportamiento de GUI permanece sin verificar |
| Otros hosts MCP | Stdio o Streamable HTTP de bucle local autenticado |
Extras opcionales: pdf, ocr, transcription y jev. Comienza con la instalación
base; habilita solo los motores que necesites. Medios,
adjuntos, implementación.
Las observaciones de conexión nativa y los límites de prueba se registran en
aceptación; el descubrimiento no establece la calidad del flujo de trabajo del modelo.
Desarrolla y contribuye
Reporta errores reproducibles y propón flujos de trabajo en Issues. Lee CONTRIBUTING; los agentes de codificación comienzan con AGENTS.md. Ejecuta las comprobaciones para el comportamiento que cambies. Una versión sustancial obtiene una ejecución completa, una compilación canónica y verificación de identidad de artefactos.
Teleloom v0.5.0 es la primera versión pública, publicada con un historial de Git nuevo.
El paquete de Python, el módulo, la CLI y el servidor MCP se llaman teleloom; las habilidades
de ejecución usan el prefijo teleloom-.
Instala desde este repositorio o sus artefactos de versión;
no se reclama distribución en PyPI. Registro de cambios · Documentación.
Licencia MIT. Inspirado por chigwell/telegram-mcp, implementado de forma independiente. Teleloom es un proyecto independiente, no afiliado a Telegram.