Telegram MCP — Nueva generación

Una integración de Telegram orientada a producción para clientes compatibles con MCP, mantenida por LoneVertex y construida sobre Telethon y el Model Context Protocol. Este repositorio conserva la superficie funcional de Telegram del upstream y añade niveles de herramientas explícitos, controles de mutación con cierre ante fallos, límites de concurrencia por clave, reintentos acotados, caché local en SQLite/FTS5, rutas de medios más seguras, puntos de entrada de paquete y CI reproducible.

Postura por defecto: stdio local, nivel de herramientas core, sin escrituras en Telegram, sin operaciones destructivas y sin raíces de sistema de archivos no verificadas.

Gobernanza del proyecto: Contribuciones · Política de seguridad · Apache License 2.0

Qué se incluye

La implementación registra 128 herramientas: las 125 herramientas del upstream que cubren cuentas, chats, contactos, mensajes, grupos, medios, perfiles, carpetas y eventos entrantes, más cache_health, search_cached_messages y sync_chat_cache. La procedencia del upstream se conserva en el commit 52cca204d945e4e6b0801a9d9723320c2a4b63; el paquete de nueva generación está en la versión 4.0.1.

Establezca TELEGRAM_MCP_TIER para seleccionar un nivel. El nivel seleccionado controla qué herramientas se registran. TELEGRAM_SEND_ENABLED controla de forma independiente si las operaciones de escritura pueden ejecutarse, y TELEGRAM_DESTRUCTIVE_ENABLED es una segunda puerta para las acciones destructivas/administrativas. El servidor devuelve una respuesta estructurada nothing_sent o nothing_done cuando una puerta bloquea una llamada.

Related MCP server: telegram-mcp

Inicio rápido

Use Python 3.11 o 3.12. Obtenga las credenciales de la API de Telegram en my.telegram.org/apps y genere una sesión autorizada fuera del proceso MCP con el generador de sesiones incluido.

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

Para el desarrollo del paquete y la validación de los lanzamientos:

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

El servidor es intencionalmente no interactivo. Use telegram-mcp-generate-session antes del arranque y mantenga privada la cadena de sesión resultante. Nunca comprometa .env, un archivo .session de Telethon, hashes de API o cadenas de sesión.

Configuración

La plantilla completa sin secretos está en .env.example. Los controles relevantes se resumen a continuación.

La construcción de la configuración no tiene efectos secundarios. Las credenciales y la autorización se comprueban cuando se inicia un cliente en vivo, no cuando las herramientas locales importan el paquete. El estado en tiempo de ejecución se crea bajo directorios de solo propietario cuando una operación de caché o de sesión lo requiere.

Clientes y transportes MCP

Vea config/mcp-configs.md para ejemplos sin secretos dirigidos a clientes MCP de escritorio. Se prefiere el stdio local. Streamable HTTP está disponible para un servicio local de larga duración:

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

No exponga el endpoint HTTP sin autenticación directamente a la Internet pública. Si se usa un proxy inverso, configure autenticación, TLS, hosts permitidos, orígenes permitidos y controles de red. El servidor conserva la protección contra DNS rebinding cuando MCP_ALLOWED_HOSTS está configurado.

Concurrencia y fiabilidad

Cada cuenta está protegida por un mutex asíncrono por clave y un token bucket. Las llamadas que comparten una cuenta se serializan en el límite del adaptador, mientras que la expansión de solo lectura en varias cuentas sigue siendo posible entre distintas etiquetas de cuenta. FloodWait y los fallos de conexión transitorios usan una única política de reintentos acotados con backoff exponencial y jitter. Los bloqueos advisory a nivel de sesión se mantienen para evitar que procesos duplicados usen simultáneamente la misma clave de autenticación de Telegram.

La caché local usa el modo WAL de SQLite, claves foráneas, conexiones de corta vida, transaciones explícitas, índices para el acceso por chat/fecha/remitente/tema y FTS5 para la búsqueda. La sincronización guarda puntos de control y usa upserts para reflejar las ediciones en lugar de duplicarlas. El trabajo con SQLite, la cación de directorios y las comprobaciones de integrdad se ejecutan en hilos de traba jo en luugar de bloquear el buce de eventos.

Medios y seguridad del sistema de archivos

Las herramientes de archivo requieren raíces MCP del cliente or raíces explícitas del lado del servidor. Las raíces vacías or no verificalbles signals produce a comportamiento de denagción totial a menos que TELEGRAM_ALLOW_SERVE_ROTS_FALLBACK se habilite intencionalmente. Las rutas se resuelven dentro de las raíces configuradas; se rechazan el path traversal y los bytes NUL, se rechazan las fugas mediante enlaces simbólicos, se aplican los límites de tamaño de medios, y los archivos generados usan permisos de solo el propietario. Las nuevas primitivas de seguridad permiten lecturas fragmentadas y sustitución atómica de la salida.

Los textos, pies de foto, nombres, etiquetas de botones, metadatos de medios y campos de eventos entrantes de Telegram son contenido de usuario no confiable. La saneación y las audiencias anotadas se conservan del upstream; los modelos no deben tratar esos campos como instrucciones.

Docker

La imagen usa una construcción de Python 3.12 en dos etapas, se ejecuta como UID 10001, guarda el estado en /var/lib/telegram-mcp y recibe las credenciales solo en el arranque.

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

El Compose vincula HTTP a 127.0.0.1:8765, usa un volumen nombrado persistente, elimina las capacidades Linux, activa no-new-privileges, monta un sistema de archivos raíz de solo lectura y proporciona un /tmp restringido. La construcción del contenedor no se ejecutó en el sandbox usado para esta entrega porque Docker no estaba disponible; el flujo de trabajo CI lo valida en un runner con Docker.

Puertas de desarrollo y publicación

El flujo de trabajo integrado en .github/workflows/ci.yml se ejecuta con Python 3.11 y 3.12, ejecuta la suite de regresión heredada del upstream además de las pruebas de la nueva generación, ejecuta comprobaciones estrictas de Ruff en las nuevas capas de producción, ejecuta comprobaciones de mypy con base de paquete explícita, compila el paquete, genera una wheel/sdist, audita las dependencias declaradas y valida la imagen Docker y la configuración de Compose. Los adaptadores en vivo del upstream siguen cubiertos por su suite de regresión simulada heredada; los módulos lociales de confiabilidad/seguridad tienen pruebas y cobertura dedicadidas.

Propiedad, compatibilidad y procedencia

Mantenimiento del proyecto: LoneVertex.

El main.py raíz, los nombres de módulos de herramientas del upstream, el generador de sesiones, las etiquetas de cuenta, los ajustes de proxy, las variables de transporte MCP, el filtro de exposición heredado y la licencia Apache-2.0 del upstream se conservan para la compatibilidad. El nuevo punto de entrada del paquete es telegram_mcp.runner:main y se admite python -m telegram_mcp. El código fuente del upstream y su atribución siguen en el historial de Git y en AUDIT_REPORT.md.

Solución de problemas

Si al inicio se informa que no hay sesión configurada, genere una sesión autorizada y configure TELEGRAM_SESSION_STRING o un nombre de sesión de archivo válido. Si una escritura devuelve MutationDisabled, configure TELEGRAM_SEND_ENABLED a true y reinicie; para borrado o administración, además estabrica TELEGRAM_DESTRUCTIVE_ENABLED en true. Si una herramienta de archivo informa que no hay raíces disponibles, configure las raíces MCP del cliente o pase una raíz permitida del servidor como argumento posicional. Si un flood de Telegram supera el máximo configurado, la llamada devuelve intencionalmente un error en lugar de quedarse dormida indefinidamente. Use cache_health para inspeccionar la integridad de SQLite/FTS5 local sin contactar con Telegram.

Referencias

Licencia

Apache License 2.0. Ver LICENSE.