better-telegram-mcp

Better Telegram MCP

mcp-name: io.github.n24q02m/better-telegram-mcp

Telegram para agentes de IA: mensajes, chats, medios y contactos en modos de bot y cuenta de usuario.

ARCHIVADO 2026-09-13 — Este repositorio ya no se mantiene. Usa la API oficial de Telegram Bot en lugar de este servidor MCP. Las instalaciones existentes siguen funcionando pero no reciben actualizaciones ni soporte.

Proyectos hermanos de n24q02m (clic para expandir)

Proyecto	Eslogan	Etiqueta
agent-chat-plugin	Agentes de IA pares chatean en una carpeta compartida — sin relevo humano, sin orquestador, tra...	Herramientas
better-code-review-graph	Grafo de conocimiento para revisiones de código eficientes en tokens — búsqueda semántica y llam...	MCP
better-drive	Sincronización bidireccional de Google Drive con filtro .driveignore — motor rclone, bandeja de Windows	Herramientas
better-email-mcp	Correo IMAP/SMTP para agentes de IA — leer, enviar, organizar carpetas y gestionar archivos adj...	MCP
better-godot-mcp	Servidor MCP compuesto para Godot Engine — 17 herramientas compuestas para desarrollo de juegos asistido por IA...	MCP
better-notion-mcp	Notion centrado en Markdown para agentes de IA — páginas, bases de datos, bloques y comentarios...	MCP
better-semantic-release	Bifurcación directa de python-semantic-release con protecciones de seguridad de lanzamiento integradas (orp...	Herramientas
better-telegram-mcp	Telegram para agentes de IA — mensajes, chats, medios y contactos en ambos modos de bo...	MCP
better-workspace-mcp	Servidor MCP de Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Mercado de plugins de Claude Code para los servidores MCP de n24q02m — instalar búsqueda web se...	Mercado
imagine-mcp	Comprensión y generación de imágenes y videos para agentes de IA — en Gemini, Op...	MCP
jules-task-archiver	Extensión de Chrome para operaciones masivas en tareas de Jules mediante la API batchexecute — a...	Herramientas
mcp-core	Base compartida para construir servidores MCP — transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memoria de IA persistente con búsqueda híbrida y sincronización integrada. Abierta, gratuita, ilimit...	MCP
qwen3-embed	Incrustación y reordenamiento de texto Qwen3 ligero mediante ONNX Runtime y GGUF	Biblioteca
skret	Secretos sin el servidor.	CLI
tacet	Una cascada neuro-simbólica autodestiladora que amortiza el costo de LLM en conocimiento...	Herramientas
web-core	Paquete de infraestructura web compartida para búsqueda, extracción, seguridad HTTP y al...	Biblioteca
wet-mcp	Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y bib...	MCP

Tabla de contenidos

• Características
• Estado
• Instalación
• Smithery
• Configuración
• CLI
• Documentación
• Herramientas
• Comparación
• Seguridad
• Compilar desde el código fuente
• Desplegar en Cloudflare
• Modelo de confianza
• Licencia

Características

• Modo dual -- API de Bot (httpx) para bots, MTProto (Telethon) para cuentas de usuario
• 7 herramientas con despacho de acciones: message, chat, media, contact, config, help, config__open_relay
• Detección automática de modo -- Configura el token del bot para el modo bot, o las credenciales de API para el modo usuario
• Autenticación OTP basada en web -- El formulario de relevo del navegador en modo HTTP maneja teléfono, OTP y 2FA para cuentas de usuario
• Autenticación CLI local -- auth configura una máquina de un solo usuario; login sigue siendo un alias obsoleto
• Anotaciones de herramientas -- Cada herramienta declara readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• Recursos MCP -- Documentación disponible como recursos telegram://docs/*
• Seguridad reforzada -- Protección SSRF, prevención de recorrido de rutas, saneamiento de errores

Estado

El ejecutable usa por defecto stdio para operación local de un solo usuario. HTTP se activa con --http, MCP_TRANSPORT=http o TRANSPORT_MODE=http; HTTP es el modo de despliegue para la configuración de relevo del navegador y acceso opcional multiusuario. La matriz canónica de modos de pila nombra relevo remoto HTTP como el valor predeterminado de Telegram desplegado, por lo que cambiar el valor predeterminado del ejecutable requiere una decisión de contrato de transporte y una migración separadas. Este repositorio no afirma silenciosamente que esos dos valores predeterminados ya estén reconciliados.

No hay capas de puente daemon ni auto-generación desde stdio. Consulta Descripción general de modos para el modelo de transporte completo.

Los servidores MCP hermanos del mismo autor se enumeran en la sección plegable anterior — comparten esta arquitectura, por lo que los patrones de instalación se transfieren.

Instalación

# Local default: plugin install via Claude Code (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Method 1 (CLI): direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx better-telegram-mcp

# Method 2 (fallback): Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp

# Method 3 (recommended for user mode / multi-device / OAuth): Docker HTTP
docker run -d --name better-telegram-mcp-http -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PUBLIC_URL=https://telegram.example.com \
  -e MCP_DCR_SERVER_SECRET=<32+ random bytes> \
  n24q02m/better-telegram-mcp:latest

Matriz de instalación

Cliente	Instalación
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-telegram-mcp@n24q02m-plugins (modo bot stdio), o claude mcp add como en el bloque anterior
Cursor / Windsurf / Gemini CLI / cualquier cliente MCP	JSON mcpServers en la configuración del cliente — stdio command, o type: "http" + url apuntando a un despliegue

Guías completas por cliente: mcp.n24q02m.com/servers/better-telegram-mcp/setup/.

El modo stdio es el modo local de un solo usuario. El modo bot usa TELEGRAM_BOT_TOKEN; el modo usuario se puede configurar localmente con better-telegram-mcp auth --phone <+number>. El modo usuario HTTP usa el formulario de relevo basado en navegador en /authorize para teléfono, OTP y 2FA.

Punto final remoto -- un despliegue HTTP está protegido por OAuth y sirve /mcp. Apunta cualquier cliente MCP que hable Streamable HTTP + OAuth 2.1 a https://<your-host>/mcp; cada usuario completa la configuración de relevo del navegador (token de bot, o teléfono + OTP) en la primera conexión. Para ejecutar uno, usa el método Docker HTTP anterior o el despliegue en Cloudflare a continuación.

Las matrices de configuración completas están en el sitio de documentación canónico mcp.n24q02m.com/servers/better-telegram-mcp/setup/, y los fragmentos para pegar al agente en claude-plugins/plugins/better-telegram-mcp/setup-with-agent.md.

Smithery

También listado en Smithery. Según smithery.yaml, Smithery inicia el servidor sobre stdio con uvx --python 3.13 better-telegram-mcp y no toma configuración en el momento de la instalación (configSchema vacío) — las credenciales se proporcionan en tiempo de ejecución a través del propio flujo de configuración del servidor: la variable de entorno TELEGRAM_BOT_TOKEN o el comando local auth para el modo stdio de un solo usuario, o el formulario de relevo del navegador para el modo usuario HTTP (consulta Configuración).

Configuración

La configuración se carga desde variables de entorno con prefijo TELEGRAM_ (Configuración de Pydantic).

Modo stdio (local de un solo usuario):

Variable	Requerida	Descripción
TELEGRAM_BOT_TOKEN	Sí	Token de bot de @BotFather (formato 123456789:ABCdef...)

Modo HTTP (bot + usuario): las credenciales se ingresan mediante el formulario de relevo del navegador, no variables de entorno. Variables de entorno del lado del servidor para autoalojamiento:

Variable	Requerida	Predeterminado	Descripción
MCP_TRANSPORT	Sí	stdio	Configúralo en http para habilitar el modo HTTP (la bandera CLI --http o TRANSPORT_MODE=http también funcionan)
PUBLIC_URL	Autoalojamiento	--	URL pública del servidor; su presencia habilita la rama OAuth multiusuario
MCP_DCR_SERVER_SECRET	Autoalojamiento	--	Secreto compartido OAuth multiusuario, 32+ bytes aleatorios (el DCR_SERVER_SECRET heredado aún se acepta)
HOST	No	0.0.0.0	Dirección de enlace
PORT	No	8080	Puerto HTTP

Credenciales de modo usuario (anulaciones opcionales): TELEGRAM_API_ID y TELEGRAM_API_HASH vienen con valores predeterminados públicos de desarrollo integrados, por lo que solo TELEGRAM_PHONE es necesario para iniciar el flujo de teléfono + OTP. TELEGRAM_SESSION_NAME y TELEGRAM_DATA_DIR personalizan la ubicación del archivo de sesión de Telethon. No existe la variable de entorno TELEGRAM_PASSWORD — el 2FA del relevo HTTP se ingresa a través de la interfaz web; la autenticación CLI local solicita interactivamente y nunca lo almacena en el entorno.

CLI

El script de consola better-telegram-mcp (instalado por uvx / pip) inicia el servidor cuando se ejecuta sin subcomando, y expone algunos subcomandos de operador para la configuración local de un solo usuario y diagnósticos. Cualquier bandera que no sea un subcomando se pasa directamente al servidor (por ejemplo, --http).

better-telegram-mcp            # start the MCP server (stdio, bot mode by default)
better-telegram-mcp --http     # start in HTTP mode
better-telegram-mcp --version  # print the version

Subcomandos (better-telegram-mcp <subcommand>):

Subcomando	Uso	Descripción
auth	auth --bot-token <token> o auth --phone <+number>	Autentica esta máquina (un solo usuario). El modo bot valida el token; el modo teléfono ejecuta el flujo interactivo OTP/2FA y almacena la sesión de Telethon en disco
login	Mismos argumentos que auth	Alias obsoleto de auth
logout	logout	Revoca la sesión de Telegram en el servidor, elimina el archivo de sesión local y borra las credenciales guardadas
config	config status, config delete [--yes]	Muestra o elimina la configuración de credenciales locales guardadas (las anulaciones de entorno aún tienen prioridad al iniciar el servidor)
relay	relay status, relay open, relay reset	Inspecciona, abre (imprime una URL de configuración nueva) o restablece la sesión de configuración de relevo del navegador
doctor	doctor	Imprime diagnósticos del entorno — versión de Python, backend de credenciales, estado de configuración + relevo, y modo de transporte

# Bot mode: validate a bot token and save it to the local config
better-telegram-mcp auth --bot-token 123456:ABC-DEF

# User mode: interactive phone + OTP (+ 2FA if enabled) sign-in
better-telegram-mcp auth --phone +15551234567

# Remove local credentials and revoke the session
better-telegram-mcp logout

El comando auth, su alias obsoleto login y logout son de un solo usuario y solo para la máquina local — escriben la sesión de Telethon en disco y la configuración cifrada de un solo usuario, así que ejecútalos en la máquina que aloja el servidor stdio. Para despliegues HTTP remotos / multiusuario, las credenciales se ingresan a través del formulario de relevo del navegador en su lugar (consulta el punto final remoto y Configuración).

Documentación

Documentación completa en mcp.n24q02m.com/servers/better-telegram-mcp/:

• Configuración -- métodos de instalación para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Descripción general de modos -- stdio (local, un solo usuario) y HTTP (remoto, OAuth 2.1)
• Configuración multiusuario -- modelo de credenciales por JWT-sub

Instalar con agente de IA -- pega esto a tu agente de codificación de IA:

Instala el servidor MCP better-telegram-mcp siguiendo los pasos en https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Herramientas

Herramienta	Acciones	Descripción
message	send, edit, delete, forward, pin, react, search, history	Enviar, editar, eliminar, reenviar mensajes. Fijar, reaccionar, buscar, ver historial
chat	list, info, create, join, leave, members, admin, settings, topics	Listar y gestionar chats, grupos, canales. Miembros, administración, temas del foro
media	send_photo, send_file, send_voice, send_video, download	Enviar fotos, archivos, notas de voz, videos. Descargar medios de mensajes
contact	list, search, add, block	Listar, buscar, agregar contactos. Bloquear/desbloquear usuarios (solo modo usuario)
config	status, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete	Estado del servidor, configuración de ejecución, caché, configuración de credenciales (relay, estado, restablecer, completar)
help	--	Documentación completa para cualquier tema
config__open_relay	--	Re-activar el flujo de configuración del relay de cero (imprime una nueva URL de relay para el formulario del navegador). Registrado a través de mcp-core's register_open_relay_tool para que un LLM pueda reiniciar la configuración sin reinicio manual

Recursos MCP

URI	Contenido
telegram://docs/messages	Referencia de operaciones de mensajes
telegram://docs/chats	Referencia de gestión de chats
telegram://docs/media	Referencia de envío/descarga de medios
telegram://docs/contacts	Referencia de gestión de contactos
telegram://stats	Toda la documentación combinada

Comparación

Cómo se compara better-telegram-mcp con competidores directos en cada pilar:

Capacidad	better-telegram-mcp	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Modo API de bot (token de bot)	Sí (httpx)	No	No	Sí
Modo cuenta de usuario MTProto	Sí (Telethon)	Sí	Sí	No
Enviar / editar / eliminar mensajes	Sí	Sí	No (solo lectura, solo borrador)	Sí (solo envío)
Descarga de medios de mensajes	Sí	Sí	Sí	No (solo envío)
Gestión de contactos (agregar / bloquear)	Sí (modo usuario)	Sí	Parcial (solo listar)	No
Autenticación OTP web / navegador	Sí (formulario relay, sin interfaz)	No (cadena de sesión CLI)	No (inicio de sesión CLI)	No (token de bot preconfigurado)
Remoto multiusuario, aislamiento por usuario	Sí (backends por JWT-sub)	No	No	No
Protección SSRF	Sí (validación de URL + bloqueo de DNS-rebinding)	?	?	No
Prevención de path traversal	Sí	Sí (ruta real permitida)	?	No
Auto-alojable	Sí	Sí	Sí	Sí

Seguridad

• Protección SSRF -- Todas las URLs validadas contra rangos de IP internos/privados, bloqueo de DNS rebinding
• Prevención de Path Traversal -- Rutas de archivo validadas, directorios sensibles bloqueados
• Seguridad de archivos de sesión -- Permisos 600, 2FA solo a través de la interfaz web (nunca almacenado en variables de entorno)
• Sanitización de errores -- Las credenciales nunca se filtran en mensajes de error

Compilar desde el código fuente

git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp

Desplegar en Cloudflare

Ejecuta tu propio better-telegram-mcp multiusuario sin servidor en Cloudflare (Worker + Container + KV).

Despliegue (gestionado por CD)

Los despliegues gestionados pasan por CI, nunca a mano: el trabajo deploy-cf en .github/workflows/cd.yml se ejecuta después de un lanzamiento, verifica la etiqueta lanzada, compila la imagen inmutable http en la versión lanzada, la envía al registro gestionado de Cloudflare, despliega y se controla mediante una verificación canary — una instancia gestionada solo puede ejecutar una etiqueta de lanzamiento exacta. El wrangler deploy manual contra una instancia gestionada/operada no está permitido: rompe la correspondencia etiqueta de lanzamiento ↔ imagen en vivo, y la siguiente ejecución de CD lo sobrescribiría.

El trabajo está controlado por la variable de Actions del repositorio CF_HOSTED_ENABLED — actualmente false, por lo que los lanzamientos no publican un endpoint alojado (según el Modelo de confianza, no hay un endpoint público de Telegram alojado por un operador). Para ejecutar tu propia instancia, usa los pasos de auto-alojamiento a continuación.

Requisitos previos: una cuenta de Cloudflare en el plan de pago Workers -- requerido para Containers (el nivel gratuito de Cloudflare no incluye Containers) -- y el CLI wrangler.

1. git clone https://github.com/n24q02m/better-telegram-mcp && cd better-telegram-mcp
2. wrangler login
3. Aprovisiona el espacio de nombres KV y pega su id en wrangler.jsonc:

   wrangler kv namespace create better-telegram-kv
   

4. Envía la imagen del contenedor a tu registro gestionado de Cloudflare (los Containers de CF no pueden extraer de registros externos directamente), luego establece <YOUR_ACCOUNT_ID> en wrangler.jsonc:

   docker pull ghcr.io/n24q02m/better-telegram-mcp:beta
   docker tag ghcr.io/n24q02m/better-telegram-mcp:beta better-telegram-mcp:beta
   wrangler containers push better-telegram-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/better-telegram-mcp:beta
   

5. Establece <YOUR_PUBLIC_URL> (por ejemplo, https://telegram.example.com) y <YOUR_WORKER_DOMAIN> (por ejemplo, telegram.example.com) en wrangler.jsonc, luego establece los secretos:

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put MCP_DCR_SERVER_SECRET
   

   CREDENTIAL_SECRET es OBLIGATORIO: deriva una clave de firma OAuth determinista para que la identidad del usuario sobreviva a la recreación del contenedor. MCP_RELAY_PASSWORD controla el formulario de configuración del navegador (puerta frontal compartida Gate A); MCP_DCR_SERVER_SECRET (32+ bytes aleatorios) marca el despliegue como intencionalmente multiusuario.
6. wrangler deploy, luego completa la configuración en el formulario relay del navegador en el dominio de tu Worker -- cada usuario ingresa su propio token de bot o teléfono + OTP allí, por lo que no hay credenciales de Telegram por usuario en el Worker.

El almacenamiento se asigna a Cloudflare a través de MCP_STORAGE_BACKEND=cf-kv (la configuración cifrada). NO establezcas MCP_AUTH_DISABLE en un despliegue compartido/público -- colapsa todos los usuarios en un solo cubo de credenciales.

Modelo de confianza

Este plugin implementa TC-NearZK (en memoria, efímero). Consulta el modelo de confianza de mcp-core para la clasificación completa.

El proyecto ya no opera un endpoint de Telegram alojado por n24q02m. El modo HTTP está disponible solo en infraestructura que un operador despliega y controla.

Modo	Almacenamiento	Cifrado	¿Quién puede leer tus datos?
HTTP auto-alojado (opt-in)	dict[sub] = MTProtoSession en memoria	Solo en proceso	Proceso del servidor controlado por el operador (se borra al reiniciar)
stdio	~/.config/mcp/config.enc (credenciales) + ~/.better-telegram-mcp/<name>.session (sesión Telethon)	AES-GCM, clave vinculada a la máquina	Solo tu usuario del SO (permiso de archivo 0600)

Nombre de usuario del espacio de trabajo (formulario HTTP de configuración)

El formulario de configuración del navegador tiene un campo opcional de nombre de usuario del espacio de trabajo. Ingresar el mismo nombre de usuario siempre te lleva al mismo cubo por sub, por lo que tu sesión permanece accesible a través de una reautorización y entre dispositivos, en lugar de estar vinculada al sujeto único emitido para cada ida y vuelta de /authorize. Dejarlo en blanco mantiene el comportamiento anterior por autorización.

Límite de confianza: cuando el formulario está controlado por un MCP_RELAY_PASSWORD compartido, el nombre de usuario es una clave de partición, no un secreto -- cualquiera que conozca esa contraseña puede escribir cualquier nombre de usuario y llegar a ese cubo. Eso está bien para un grupo de confianza; un despliegue multiinquilino no confiable necesita un secreto por usuario o OAuth delegado en su lugar.

Migración única: los usuarios existentes deben reautenticarse una vez después de este cambio. Nada se elimina; las sesiones almacenadas bajo el antiguo sujeto aleatorio simplemente ya no se abordan.

Licencia

Apache-2.0 -- Consulta LICENSE.