Servidor MCP de Telegram para Claude Code, Cursor, Codex y Claude Desktop

Better-TG-CLI incluye un servidor MCP, telegram mcp, que permite a un cliente de IA leer y buscar en tu propia cuenta de Telegram y, cuando apruebas cada envío, escribir en ella. Se ejecuta en tu equipo por stdio y habla con Telegram directamente; nada pasa por nuestros servidores.

1. Instala la CLI

brew install thevilfer/tap/better-tg-cli   # macOS or Linux
scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli                 # Windows
npm install -g better-tg-cli                # any OS, Node 20+

El paquete de npm es un único archivo sin dependencias en ejecución; Homebrew y Scoop instalan un binario independiente que no necesita Node.

2. Inicia sesión una vez

telegram onboard      # free login key or your own API keys, then a QR code

Escaneas un código QR en Telegram desde el móvil. El código de acceso, la contraseña 2FA y la sesión nunca llegan al agente. La sesión se guarda en el Llavero de macOS, el Secret Service de Linux, DPAPI de Windows o 1Password.

3. Añádelo a tu cliente

claude mcp add telegram -- telegram mcp                     # Claude Code
codex plugin marketplace add TheVilfer/better-tg-cli         # Codex (skill and server)
codex plugin add better-tg-cli@better-tg-cli
gemini extensions install https://github.com/TheVilfer/better-tg-cli   # Gemini CLI

Para Claude Desktop, descarga better-tg-cli.mcpb de la última versión y ábrelo: no necesita Node, npm ni Homebrew.

Para Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) y otros clientes MCP, usa el formato JSON con la ruta completa que imprime which telegram, porque las apps gráficas pueden no ver el PATH de tu shell:

Configuración JSON

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

# sin instalación global:
{
  "mcpServers": {
    "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] }
  }
}

El servidor figura en el MCP Registry oficial como io.github.TheVilfer/better-tg-cli.

Qué ofrece el servidor

• telegram_read: comandos de solo lectura (bandeja, leer, buscar, hilos, temas de foros, comentarios de canales, contactos), así que los clientes pueden aprobarlo automáticamente.
• telegram_write: envíos, ediciones, reacciones, reenvíos, botones de bots. Está marcado como destructivo.
• telegram_help: una referencia con búsqueda de cada comando y opción.

Cómo se aprueban las escrituras

Tras iniciar sesión, el perfil está en modo ask. Antes de cada escritura ves la acción exacta, y solo se ejecuta cuando dices que sí. Los clientes compatibles con MCP elicitation te preguntan en su propio diálogo, así que el modelo nunca toca la aprobación; los demás pasan un código de un solo uso ligado a ese texto exacto.

telegram write-access off deja el perfil en solo lectura. Escribir sin preguntar (telegram write-access on --for 1h) requiere tu confirmación en un terminal o en un diálogo del sistema. Estos modos protegen de los errores de un agente; un agente que ejecuta comandos en tu equipo como tú aún podría leer la sesión, así que conecta esos agentes solo a chats de confianza. Los detalles están en SECURITY.md.

Agentes en la nube

Los agentes en la nube, como Grok Bot, no pueden iniciar un programa en tu equipo. Ejecuta telegram mcp --http con un token bearer y accede a él a través de un túnel; la sesión y el control de escritura se quedan en tu equipo. Los pasos están en el README.