Servidor MCP

tg mcp permite que un agente utilice un perfil mediante MCP, por stdin y stdout, sin abrir puertos de red. El servidor viene incluido en tg; no tienes que instalar nada más.

Cuándo lo necesitas. En Claude Code, Codex y otros agentes con terminal basta con tg: consume los mismos tokens y ofrece las mismas funciones. MCP sirve para clientes sin terminal, como Claude Desktop o el chat de Cursor, y para quienes quieren aprobar cada envío desde el cliente. ChatGPT o Claude en el navegador necesitan pasos adicionales: consulta acceso desde el navegador.

Este servidor se basa en el de max-cli (max mcp) y se comporta igual.

ConexiónCopy Anchor Link

Ejecuta primero tg setup --agent none en una terminal local. Configura la cuenta de Telegram; tg mcp setup conecta el cliente por separado. tg skill show explica ambas vías antes de iniciar sesión. El servidor MCP nunca inicia sesión por ti.

Codex o Claude Code en este equipo:

tg mcp doctor                # check that MCP starts and lists tools
tg mcp setup codex          # add it to Codex
tg mcp setup claude-code    # or add it to Claude Code

Pon el perfil primero, por ejemplo tg work mcp setup codex. Setup usa el comando del propio cliente y conserva los demás servidores. Si ya existe una entrada con el mismo nombre, elimínala en el cliente antes de repetir. El perfil predeterminado ofrece herramientas de escritura; setup pide revisar los permisos y repetir con --allow-writes. Esta opción confirma la instalación, sin cambiar permisos. Para limitar al agente, configura primero los permissions del perfil (más abajo).

mcp doctor no lee mensajes ni inicia sesión en Telegram. Un resultado correcto significa que la conexión inicial MCP y la lista de herramientas funcionan, no que la sesión de la cuenta sea válida. potentialWrites cuenta herramientas sin declaración de solo lectura. Los chats en navegador y móvil necesitan una conexión remota aparte (acceso remoto).

Claude Code:

claude mcp add tg -- tg mcp

Con un perfil, pon su nombre primero, como en cualquier comando:

claude mcp add tg-work -- tg work mcp

Claude Desktop, Cursor y otros: tg imprime la entrada que debes añadir a su configuración:

tg mcp config
tg work mcp config --confirm-send     # the entry with a form before every change

--confirm-send, --allow-dangerous y --yes se incluyen en la entrada tal como los indiques (más abajo).

{
  "mcpServers": {
    "tg": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/usr/lib/node_modules/@leemour/tg-cli/dist/bin/tg.js", "mcp"],
      "env": { "XDG_RUNTIME_DIR": "/run/user/1000" }
    }
  }
}

Pega la entrada dentro de mcpServers en el archivo de configuración del cliente: para Claude Desktop, ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en Windows; para Cursor, ~/.cursor/mcp.json. El comando no modifica ningún archivo.

Las rutas son completas porque un cliente iniciado desde el escritorio no ve el PATH de tu terminal; en Windows, tg es un archivo tg.cmd que un cliente sin shell no puede iniciar directamente. La entrada copia TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE y XDG_RUNTIME_DIR si están definidas; nunca copia TG_API_ID, TG_API_HASH ni la sesión.

Si instalaste Node con nvm, fnm o Volta, su ruta corresponde a una versión concreta. Vuelve a ejecutar tg mcp config si cambias de versión. Si se ejecuta desde npx, el comando lo rechaza: la caché de npx puede borrarse y la ruta dejaría de existir.

⚠ TG_CONFIG_DIR, TG_STATE_DIR y TG_CACHE_DIR cambian dónde se busca la sesión. Si están definidas en la terminal y no en el cliente MCP, o viceversa, el servidor responde "no session" aunque tg funcione en la terminal. Defínelas igual en ambos sitios o en ninguno.

⚠ En Linux, las credenciales de la aplicación están en el almacén de claves, al que se accede mediante XDG_RUNTIME_DIR. Si el cliente inicia servidores con un entorno reducido y omite esa variable, todas las herramientas indican que probablemente no pueden acceder al almacén. La entrada de tg mcp config la incluye.

Qué puede hacer el agenteCopy Anchor Link

Los permissions del perfil deciden qué herramientas se ofrecen, con los mismos niveles que los comandos (configuración):

Con los ajustes predeterminados, el agente puede enviar, editar, reaccionar, reenviar, fijar, votar y marcar chats como leídos sin opciones adicionales ni preguntas. Solo tg_messages_delete tiene nivel ask: muestra un formulario antes de eliminar. Un agente nunca elimina para todos ni cierra tus otras sesiones, sea cual sea el nivel.

Para que el agente solo lea, dale un perfil propio: tg agent session start inicia otra sesión de la misma cuenta, como otro dispositivo. Después configura cada recurso:

for key in messages reactions polls topics chats contacts account; do
  tg agent config set permissions.$key readonly
done
claude mcp add tg -- tg agent mcp

El ajuste anterior readOnly: true en ese perfil tiene el mismo efecto. Para pedir aprobación antes de cada envío, configura messages.send como ask:

tg agent config set permissions.messages.send ask

Estos niveles también se aplican a ti: en ese perfil, tg agent messages send también pregunta. Dos opciones omiten el formulario cuando el nivel es ask:

• tg mcp --allow-dangerous: sin formulario antes de eliminar.
• tg mcp --yes: sin formulario antes de cualquier otro cambio.

Un envío, edición o reenvío por MCP pasa por las mismas comprobaciones que el comando: permissions, destinatarios permitidos, límite por hora y registro de envíos (tg sends list). Además, todas las herramientas de escritura se marcan como peligrosas: VS Code y Cursor preguntan antes de cada llamada; según su documentación, Claude Code muestra un diálogo de aprobación incluso si todo lo demás se había autorizado previamente.

Marcar un chat como leído corresponde a chats.mark-read: la otra persona lo ve. Configúralo como readonly si el agente debe leer sin revelar esa actividad. tg_chats_mark_read nunca cuenta para el límite por hora.

Eliminar mensajes corresponde a messages.delete. tg_messages_delete elimina hasta 10 mensajes solo de tu vista; eliminar para todos se deja al comando que ejecutes tú. En supergrupos y canales Telegram no permite «solo para mí», por lo que allí se rechaza esta herramienta.

--allow-send, --allow-mark-read y --allow-delete ya no deciden permisos: se aceptan con un aviso para que las configuraciones antiguas sigan iniciándose. Elimínalas de la configuración del cliente.

Formulario de confirmación del propio servidorCopy Anchor Link

claude mcp add tg -- tg mcp --confirm-send

El servidor muestra un formulario antes de los cambios con nivel ask; con --confirm-send, lo muestra antes de todos, sea cual sea su nivel. En un envío muestra el chat real, con el título e identificador que resolvió a partir del nombre del agente, y el texto completo. Solo ejecuta el cambio al pulsar Accept; el formulario no tiene campos, solo ese botón. La ventana del cliente muestra los argumentos tal como los escribió el modelo (chat: "Anna"); el formulario muestra qué estás autorizando realmente ("Anna Petrova (123456)").

• Si pulsas Decline o cierras el formulario, no cambia nada; el agente recibe confirmation_required y no debe reintentarlo.
• Si el cliente no admite formularios, recibe un error: no cambia nada. Claude Code sí los muestra.
• La aprobación está vinculada a lo mostrado: si el agente cambia el chat, texto o herramienta después, no cambia nada.
• La aprobación sirve una sola vez durante 5 minutos. Reutilizar la misma respuesta no produce cambios.

HerramientasCopy Anchor Link

Las respuestas son lo que imprime el comando con --json: una lista es { items, page, limit, hasMore }, los mensajes de un chat son { items, limit, hasMore } y los identificadores son cadenas. Los errores tienen forma { error: { code, message, … } } con los códigos del CLI; los nombres de chat ambiguos devuelven candidates.

Las lecturas de Telegram se guardan en el archivo local, igual que con los comandos; las consultas de fuentes utilizan ese archivo. Cada llamada puede registrarse como ejecución (tg runs list), con nombres como mcp chats list.

Prompts y chats mediante @Copy Anchor Link

El servidor ofrece cuatro prompts preparados; en Claude Code aparecen como comandos /:

reply y review envían mediante tg_messages_send, así que si messages.send es readonly, el agente solo muestra borradores.

Los chats son recursos tg://chat/<id>; en Claude Code puedes mencionarlos con @. Cada recurso contiene el chat y sus mensajes recientes. La lista procede del archivo local y nunca se conecta a Telegram; está vacía hasta que se lea algo. Solo la lectura de un chat abre una conexión.

Cómo se mantiene la conexiónCopy Anchor Link

La primera llamada se conecta a Telegram y las siguientes reutilizan la conexión. Se cierra tras 2 minutos sin llamadas y, en cualquier caso, 5 minutos después de abrirse, para que una sesión larga del agente no consulte datos desactualizados. La siguiente llamada vuelve a conectarse. Las llamadas se ejecutan de una en una, incluso si el cliente las envía juntas.

El servidor termina cuando el cliente cierra stdin y cierra su conexión con Telegram.