better-tg-cli

Telegram para tus agentes de IA: lee, busca y resume tu propia cuenta. Solo lectura por defecto.

Documentación

Instalación · Referencia · Seguridad · Problemas · Русский · Español

https://github.com/user-attachments/assets/d143f7c7-7d50-439c-b373-cbcbff5a6675

Un cliente de línea de comandos no oficial y apto para agentes de Telegram que se ejecuta en tu propia cuenta (MTProto vía teleproto, capa TL 229). El comando es telegram: alrededor de 60 comandos para leer, buscar, escribir, bots, grupos y exportaciones, construido para que los agentes de IA (Claude Code, Codex, …) puedan manejarlo de forma económica y segura.

$ telegram inbox -n 3
48 unread in 7 chats (showing 3)
1234567890 user unread=2 Alice @alice | see you at 7?
-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | anyone tried 1.90?
-1009876543 channel unread=5 Changelog | v2.4 is out
$ telegram read @alice -n 1 --json
{"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}

[!ADVERTENCIA] Tu cuenta, tu riesgo. Este es un cliente no oficial que inicia sesión como tú. Telegram puede limitar o congelar cuentas que se comporten como bots. El riesgo es mayor para cuentas nuevas, mensajes masivos, uniones o invitaciones masivas, y cualquier cosa que parezca spam. Úsalo de la misma manera en que usarías Telegram tú mismo, mantén las escrituras desactivadas a menos que las necesites, y lee SECURITY.md antes de dejar que un agente escriba. Los autores no son responsables de cuentas restringidas.

Contenido: Por qué este fork · Instalación · Iniciar sesión · Uso · Servidor MCP · Preguntas frecuentes · Desarrollo · Privacidad · Licencia

Por qué este fork

Un fork de skillhq/telegram, rediseñado para agentes:

Capa de Telegram actual. Las respuestas de bots con contenido enriquecido (capa 228+) muestran texto real en lugar de (no text). Puedes presionar botones de bots (click) y navegar por los menús de bots.
Salida eficiente en tokens. Fuera de una TTY obtienes una línea compacta por elemento con el ID primero, y JSON en una línea con campos vacíos omitidos. --max-text recorta publicaciones largas. telegram help-all -g <word> imprime todas las banderas, generadas desde el código.
Lecturas exactas. Paginación real para --since/--until, --unread, hilos y comentarios de canales, temas de foros, get por ID, filtros de búsqueda por tipo, remitente o fecha, y me / Избранное para Mensajes Guardados.
Seguro por defecto. La cuenta es de solo lectura hasta que un humano ejecute write-access on [--for 1h] y lo confirme en un aviso de terminal o un diálogo de macOS, por lo que un agente no puede activarlo por sí mismo. Cada escritura se registra en ~/.config/tg/audit.jsonl. Los secretos viven en el Llavero de macOS, el Servicio Secreto de Linux o 1Password.
Pequeño y autónomo. El paquete npm es un archivo de 0.3 MB con cero dependencias de tiempo de ejecución. Homebrew instala un binario independiente sin Node.

Instalación

brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux
npm install -g better-tg-cli               # Node >= 20, any OS

En Windows (experimental), con Scoop o npm:

scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli

El telegram.exe de Windows no está firmado con código, por lo que SmartScreen puede advertir sobre la descarga de la versión.

telegram update actualiza una instalación existente, cualquiera que hayas usado. En una terminal, la CLI verifica nuevas versiones una vez al día. Los agentes y las tuberías nunca ven ese aviso, y TG_NO_UPDATE_CHECK=1 lo desactiva.

¿Descargando un binario de Releases manualmente en macOS? No está notarizado, así que elimina la bandera de cuarentena una vez: xattr -d com.apple.quarantine ./telegram. Homebrew se encarga de esto por ti.

No instales @skillhq/telegram. Es la compilación anterior de upstream en GramJS (capa 198).

Cada canal envía la misma versión desde una sola versión:

Dónde	Qué obtienes	Instalación
Homebrew	binario independiente	`brew install thevilfer/tap/better-tg-cli`
npm	CLI y servidor MCP (Node 20+)	`npm install -g better-tg-cli`
Scoop (Windows, experimental)	`telegram.exe` independiente	`scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket` luego `scoop install better-tg-cli`
GitHub Releases	binarios y SHA256SUMS	descarga manual
Plugin de Claude Code	habilidad y servidor MCP	ver abajo
Extensión de Claude Desktop	servidor MCP, se ejecuta en el Node integrado de Claude	descargar `.mcpb` y abrirlo
Plugin de Grok Build	habilidad y servidor MCP	ver abajo
Extensión de Gemini CLI	habilidad y servidor MCP	`gemini extensions install https://github.com/TheVilfer/better-tg-cli`
Cursor, VS Code	servidor MCP	botones de un clic
Grok Bot	servidor MCP sobre HTTP desde tu Mac	ver abajo
claude.ai, ChatGPT y otras aplicaciones que se conectan por URL	MCP a través del relé alojado, la sesión permanece en tu computadora	ver abajo
La CLI en sí	habilidad de agente para Claude Code, Codex, Cursor, Gemini CLI y 7 más	`telegram skill install`
skills.sh	habilidad de agente para cualquier agente de shell	`npx skills add TheVilfer/better-tg-cli`
MCP Registry	entrada de servidor MCP `io.github.TheVilfer/better-tg-cli`	a través de tu cliente MCP

Plugin de Claude Code

La habilidad y el servidor MCP juntos, en una sola instalación:

/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli

Ejecuta el servidor MCP a través de npx, por lo que Node 20+ es suficiente. Inicia sesión una vez con telegram auth --qr (o npx better-tg-cli auth --qr) en una terminal.

Plugin de Codex

La misma habilidad y servidor MCP como plugin de Codex (también aparece en la aplicación de escritorio de ChatGPT):

codex plugin marketplace add TheVilfer/better-tg-cli
codex plugin add better-tg-cli@better-tg-cli

Plugin de Grok Build

Grok Build instala el mismo plugin, habilidad y servidor MCP juntos:

grok plugin install TheVilfer/better-tg-cli --trust
# or add the marketplace first, then install from the /plugins menu:
grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust

Como habilidad de agente

La habilidad (skills/better-tg-cli) enseña a cualquier agente con un shell (Claude Code, Codex, Cursor, Gemini CLI, OpenCode y otros) a usar la CLI de forma segura. Verifica la configuración, nunca inicia sesión por sí sola, mantiene las escrituras detrás de tu aprobación y evita patrones propensos a baneos. La CLI lleva la habilidad y la instala por sí misma, por lo que siempre coincide con tu versión:

telegram skill install                  # every supported agent found on this machine
telegram skill install -a claude-code codex
telegram skill status                   # installed, outdated, linked or missing, per agent

Conoce Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Goose, Droid, Windsurf y Pi (telegram skill status lista las carpetas). Ejecútalo de nuevo después de telegram update para actualizar la habilidad. Una carpeta de habilidad que sea un enlace simbólico se deja sola a menos que pases --force. Para otros agentes, usa la CLI de skills:

npx skills add TheVilfer/better-tg-cli          # pick agents interactively
npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y

Iniciar sesión

A través de tu agente (lo más fácil): pídele que configure Telegram, o ejecuta telegram onboard tú mismo. Abre una página en 127.0.0.1 donde obtienes una invitación de better-tg-cli.com (vuelve a la página por sí sola) o ingresa tus propias claves, escanea un código QR y escribe tu contraseña 2FA. El agente solo inicia el comando y espera: nunca ve la invitación, el código QR ni la contraseña. La página responde solo en una ruta secreta aleatoria y se cierra cuando terminas.

Con tus propias claves de API (el valor predeterminado):

Abre https://my.telegram.org/apps, crea una aplicación y copia su api_id y api_hash.
Ejecuta telegram auth --qr e ingrésalos. Luego, en tu teléfono, ve a Configuración → Dispositivos → Vincular Dispositivo de escritorio y escanea el código QR. Ingresa tu contraseña 2FA si tienes una. El telegram auth simple pide tu número de teléfono y un código de inicio de sesión en su lugar. Si el QR no se escanea en un tema de terminal claro, ejecuta con TG_QR_INVERT=1.

Con una invitación. No necesitas tus propias claves con un token de invitación. Obtén uno en better-tg-cli.com (confirma tu correo electrónico con un código; la página está en ruso y también tiene una guía de instalación), o del mantenedor. Ejecuta telegram auth --invite --qr y pega el token, o pásalo como TG_INVITE=… o --invite -. El servicio de invitación (broker/) entrega las claves de la aplicación una vez, solo para este inicio de sesión. El api_hash no se guarda en tu máquina. Las invitaciones son personales, permiten un número limitado de inicios de sesión y pueden revocarse.

La sesión se almacena en el Llavero de macOS (servicio tg-cli), o en 1Password con --op-vault <vault>. telegram logout la elimina. En Linux va al Servicio Secreto (GNOME Keyring, KWallet, KeePassXC) a través de secret-tool, que necesita el paquete libsecret-tools. Una sesión ya guardada en el archivo de configuración se mueve allí automáticamente. Sin ningún almacén de secretos, la sesión se mantiene en ~/.config/tg/config.json5 (modo 0600) y los comandos de escritura permanecen desactivados. En Linux, write-access on se confirma en un aviso de terminal. En Windows, los secretos viven en %APPDATA%\tg\secrets.dpapi, cifrados con DPAPI para tu usuario de Windows (solo tú en esta máquina puedes descifrarlos), y write-access on pregunta en una ventana de Sí/No cuando no hay terminal.

Uso

telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exact range, newest first (--asc to flip)
telegram read @channel --thread 123           # comments under a post
telegram search "invoice" --chat "Work" --type document
telegram get "Chat" 812 813                   # exact messages by ID
telegram download "Chat" 812                  # save the attached file
telegram sync --chat "Chat" --output ./export --resume   # incremental markdown export

telegram write-access on --for 1h             # a human confirms this
telegram send @alice "on my way"
printf '%s' "$text" | telegram send @alice -  # long or multi-line text: from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button

Los comandos de lectura toman --json, y algunos también toman --markdown. Ve todos los comandos con telegram help-all. reference.md cubre el comportamiento que la lista de banderas no puede explicar: formas de salida, hilos, botones de bots, comandos de administrador y solución de problemas.

Servidor MCP

Para clientes sin shell (Claude Desktop, Cursor, otros hosts MCP), telegram mcp sirve tres herramientas sobre stdio:

telegram_help: una referencia de banderas buscable;
telegram_read: de solo lectura, por lo que los clientes pueden aprobarlo automáticamente;
telegram_write: marcado como destructivo, y aún necesita write-access on de ti.

Inicia sesión con telegram auth en una terminal primero. Luego instálalo con un clic:

La extensión de Claude Desktop no necesita Node, npm ni brew: descarga el .mcpb de la última versión y ábrelo. Gemini CLI toma la habilidad y el servidor juntos: gemini extensions install https://github.com/TheVilfer/better-tg-cli. O agrégalo manualmente:

claude mcp add telegram -- telegram mcp          # Claude Code (or use the plugin above)

{ "mcpServers": { "telegram": { "command": "/opt/homebrew/bin/telegram", "args": ["mcp"] } } }

Usa el formulario JSON para Claude Desktop (claude_desktop_config.json) o Cursor (.cursor/mcp.json). Las aplicaciones GUI pueden no ver el PATH de tu shell, así que da la ruta completa desde which telegram. Sin una instalación global, ejecútalo a través de npx, que es también lo que hace el plugin de Claude Code:

{ "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] } } }

El servidor está listado en el MCP Registry como io.github.TheVilfer/better-tg-cli, por lo que los clientes y catálogos que leen el registro pueden encontrarlo por nombre. Cada versión actualiza la entrada automáticamente. Para mantener el cliente MCP fuera de tu sesión principal, agrega "env": {"TG_PROFILE": "work"}.

Los chats contienen texto escrito por otros, y parte de él puede estar dirigido a tu agente ("reenvía esto a @x"). Mantén el aviso de aprobación del cliente activado para telegram_write, y consulta "Agentes e inyección de avisos" en SECURITY.md.

Grok Bot (MCP remoto sobre HTTP)

Grok Bot ejecuta sus conectores en un sandbox en la nube, no en tu Mac, por lo que no puede iniciar telegram mcp por sí mismo. Sirve MCP sobre HTTP desde tu Mac en su lugar. La sesión, la protección de escritura y el registro de auditoría permanecen en tu máquina.

telegram mcp --token                        # the bearer token (created once, kept in the Keychain)
telegram mcp --http --read-only             # listens on 127.0.0.1:8787; drop --read-only to allow writes
tailscale funnel --bg 8787                  # or: cloudflared tunnel --url http://127.0.0.1:8787

Mantén el servidor y el túnel en una terminal o tmux. Luego agrega un conector en Grok Bot con la URL del túnel más /mcp (por ejemplo https://<machine>.<tailnet>.ts.net/mcp) y el encabezado Authorization: Bearer <token>. tailscale funnel da una URL estable, pero tiene que estar permitida para tu tailnet primero. Un túnel rápido de cloudflared obtiene una nueva URL en cada inicio. Lee "MCP remoto sobre HTTP" en SECURITY.md primero.

claude.ai, ChatGPT y otras aplicaciones (relé alojado)

claude.ai (web y móvil), ChatGPT y otras aplicaciones que agregan servidores MCP por URL inician sesión con OAuth y no pueden iniciar un programa local. El relé alojado en https://mcp.better-tg-cli.com/mcp los conecta a telegram mcp --remote en tu computadora, que mantiene la sesión, la protección de escritura y el registro de auditoría. Sin túnel, sin token para pegar.

telegram mcp --remote --read-only        # keep it running (tmux, or a login item); drop --read-only to allow writes
telegram remote email you@example.com    # once: link your email (a code is mailed to confirm it)

En macOS, inicia --remote en una terminal en el propio Mac (o una sesión de tmux iniciada allí), no a través de SSH: el diálogo de confirmación no puede aparecer en una sesión SSH, por lo que cada aplicación sería rechazada. En la aplicación, añade un conector personalizado con la URL https://mcp.better-tg-cli.com/mcp. Su página de inicio de sesión te pide tu correo electrónico y te envía un código; introdúcelo y luego confirma en el diálogo de tu computadora. Sin un correo vinculado, telegram remote pair proporciona un código de un solo uso para la misma página. Un agente no puede responder a ese diálogo, así que nada se conecta sin ti. telegram remote clients lista las aplicaciones conectadas, telegram remote revoke <id> (o --all) las desconecta, y telegram remote reset también reemplaza la clave de dispositivo de esta computadora. Cuando la computadora está apagada, la aplicación muestra "tu computadora está fuera de línea". El relé pasa las solicitudes sin almacenarlas, pero sí las ve: lee "Hosted relay" en SECURITY.md. Su código está en relay/.

FAQ

¿Telegram prohibirá mi cuenta? Usar tu propia cuenta desde un cliente de terceros está permitido por los términos de la API de Telegram. Lo que hace que las cuentas sean limitadas es un comportamiento que parece de bot: mensajes masivos, uniones o invitaciones masivas, spam y cuentas nuevas que hacen mucho a la vez. Úsalo como usarías Telegram tú mismo. La habilidad indica a los agentes que eviten estos patrones.

¿Esto es un bot? No. Inicia sesión como tú a través de MTProto, como Telegram Desktop, y ve exactamente lo que ves. Los bots no pueden leer tus chats; esto sí puede.

¿Puede un agente enviar mensajes por su cuenta? Solo después de que actives la escritura. telegram write-access on te pide que confirmes en la terminal o en un diálogo de macOS, que un agente no puede responder. La escritura luego necesita un chat exacto, y cada uno se registra. A través de MCP, escribir es una herramienta separada que los clientes pueden pedirte que apruebes cada vez. Los detalles están en SECURITY.md.

¿Leer marca los mensajes como leídos? No. read, inbox y search dejan los chats sin leer. Solo telegram mark-read los marca.

¿Necesito mis propias claves de API? Sí, desde my.telegram.org/apps. Son gratuitas y tardan un minuto en crearse. Con una invitación de better-tg-cli.com, telegram auth --invite --qr te inicia sesión sin ellas.

¿Dónde se almacena mi sesión y quién puede ver mis mensajes? La sesión está en el Llavero de macOS, el Servicio Secreto de Linux o 1Password. La CLI habla directamente con Telegram y no tiene análisis. Los únicos otros hosts son npm para una verificación diaria de versión y el servicio de invitación al iniciar sesión. Consulta PRIVACY.md.

¿Puedo usar varias cuentas? Sí, con TG_PROFILE: cada perfil tiene su propio inicio de sesión, configuración y elementos del Llavero, por ejemplo TG_PROFILE=work telegram auth --qr. El cambio adecuado de cuentas está rastreado en #5.

¿Funciona en Windows? Sí, experimentalmente: scoop install better-tg-cli o npm. Los secretos se almacenan con DPAPI de Windows y la CI ejecuta las pruebas en Windows, pero el uso en vivo allí está menos probado que en macOS y Linux. Por favor, reporta problemas en los issues.

¿Puedo usarlo desde Grok Bot, ChatGPT u otro agente en la nube? Los agentes en la nube no pueden iniciar un programa en tu computadora, así que ejecuta el servidor MCP a través de HTTP y accede a él mediante un túnel. Consulta Grok Bot.

¿Cómo actualizo? Ejecuta telegram update. Usa el mismo canal desde el que instalaste: Homebrew, npm o un binario de lanzamiento. Si instalaste la habilidad del agente con telegram skill install, ejecútala de nuevo para actualizarla.

Desarrollo

DEVELOPMENT.md cubre:

ejecutar desde el código fuente (scripts/tg-dev);
perfiles de desarrollo aislados (TG_PROFILE) que nunca tocan tu sesión real;
servidores de prueba de Telegram;
depuración de editor y pruebas.

Los lanzamientos se cortan con scripts/release.sh (un PR de lanzamiento; la versión proviene de los títulos del PR), luego scripts/release.sh tag después de la fusión. Una etiqueta compila los binarios y publica en GitHub Releases, npm (publicación confiable con procedencia), el tap de Homebrew y el Registro MCP. Consulta CONTRIBUTING.md.

Desinstalación

telegram logout elimina la sesión guardada. Para terminarla también en el lado de Telegram, termínala en Telegram → Configuración → Dispositivos.
telegram skill uninstall elimina la habilidad de los agentes en los que se instaló.
Elimina el programa: brew uninstall better-tg-cli, npm uninstall -g better-tg-cli o scoop uninstall better-tg-cli. Para un binario de Releases, elimina telegram / telegram.exe.
Elimina la carpeta de configuración: ~/.config/tg (%APPDATA%\tg en Windows), más ~/.config/tg-<profile> para cualquier TG_PROFILE que hayas usado. En Windows, esto también elimina el archivo de secretos DPAPI. En otros lugares, el api_hash y el indicador de acceso de escritura permanecen en el almacén de secretos: elimina los elementos tg-cli en Acceso a Llaveros (o secret-tool clear service tg-cli), o el elemento en tu bóveda de 1Password.

Privacidad

Sin análisis. El único servicio que ejecutamos es el intermediario de invitaciones opcional, que nunca ve tus mensajes o sesión. Consulta PRIVACY.md para los tres hosts con los que habla la CLI y lo que almacena localmente.

Política de firma de código

Los binarios de Windows se compilan desde este repositorio solo mediante GitHub Actions (.github/workflows/release.yml), nunca en una máquina personal. Hemos solicitado la firma de código gratuita de SignPath Foundation; una vez que esté en su lugar, los binarios de lanzamiento llevarán: Firma de código gratuita proporcionada por SignPath.io, certificado por SignPath Foundation. Hasta entonces, el telegram.exe de Windows no está firmado; los binarios de macOS están firmados ad-hoc.

Committers y revisores: @TheVilfer
Aprobadores (cada lanzamiento firmado): @TheVilfer
Política de privacidad: PRIVACY.md. La CLI solo habla con Telegram, con el intermediario de invitaciones cuando inicias sesión con una invitación, y con el registro npm para una verificación diaria de actualización en una terminal (desactivada con TG_NO_UPDATE_CHECK=1).

Licencia

MIT, consulta LICENSE. Basado en skillhq/telegram por Derek Rein. No afiliado ni respaldado por Telegram; "Telegram" es una marca comercial de su propietario. Úsalo de acuerdo con los Términos de Servicio de la API de Telegram.