Configurar el servidor MCP de Telegram en Claude Code
Configura el servidor MCP de Telegram en Claude Desktop, Cursor u otra app MCP, elige qué puede leer o enviar el agente y revisa las herramientas que recibe.
MCP y skills →Qué aporta MCP, cómo conectar tu cliente y cómo leer esta documentación.Esta es la referencia técnica de MCP para este mensajero. Consulta herramientas, ajustes y permisos; la guía común enlazada te ayuda a elegir y configurar la primera conexión.
Esta página le ayuda cuando desea que una aplicación de IA sin terminal funcione con su Telegram, por ejemplo Claude Desktop o el chat en Cursor. También ayuda cuando quieres que la propia aplicación te pregunte antes de cada acción. Después de leerlo, puede conectar la aplicación a su cuenta, elegir lo que puede hacer el agente y usar indicaciones listas y menciones de chat.
Algunos términos primero:
- MCP (Model Context Protocol) es una forma estándar para que una aplicación de IA utilice herramientas externas. La aplicación es el cliente MCP;
tg personal mcp servees el servidor MCP. - Una herramienta es una acción que el servidor ofrece al agente, como "leer" o "escribir".
- Una petición preparada (prompt) es una tarea lista que la aplicación muestra como un comando, como "ponerse al día con los chats no leídos".
- Un recurso son datos que la aplicación puede adjuntar a la conversación, como un chat.
- Un perfil es un conjunto de configuraciones y un inicio de sesión en
tg; ver perfiles.
El servidor viene con tg; no hay nada más que instalar. De forma predeterminada, se comunica con la aplicación a través de stdin y stdout. En su lugar, tg personal mcp serve --http --public-url lo sirve en un puerto local detrás de su túnel HTTPS.
¿Lo necesitas?
Un agente de IA que puede ejecutar comandos en una terminal (por ejemplo, Claude Code, Codex, Cursor Agent o Gemini CLI) no necesita MCP. Llama directamente a tg, mediante la interfaz de línea de comandos; aprende cómo hacerlo gracias a la skill que imprime tg skill show. MCP es para:
- aplicaciones sin terminal, como Claude Desktop o Cursor Chat;
- cualquiera que quiera que la aplicación pregunte antes de cada envío.
Para ChatGPT o Claude en el navegador, use tg personal mcp serve --http; consulte conectar un navegador o una aplicación de teléfono.
Lo que da el servidor
| Qué | Qué hace |
|---|---|
| Tres herramientas | Busque un comando y luego ejecútelo como lectura o escritura |
| Seis peticiones preparadas | Ponte al día, responde, busca, revisa, abre tareas, vincula conversaciones |
Chats de @ | Adjuntar un chat y sus mensajes recientes a la conversación |
La skill, tg://skill | El mismo texto que tg skill show |
| Gráficos | Estadísticas de un chat como imagen JSON o PNG |
| Permisos | El perfil decide qué comandos ve el agente |
Las herramientas personales utilizan el mismo catálogo que max. Telegram también tiene temas.
Conexión
Primero ejecute tg personal setup --agent none en una terminal local. Inicia sesión en su cuenta de Telegram. El servidor MCP nunca inicia sesión por usted. Luego, tg personal mcp add conecta la aplicación, como un paso separado. Un agente puede leer tg skill show antes de iniciar sesión; explica ambos pasos.
Codex o Claude Code en este equipo:
tg personal mcp check # check that MCP starts and lists tools
tg personal mcp add codex # add it to Codex
tg personal mcp add claude-code # or add it to Claude CodePonga un perfil primero, por ejemplo tg work mcp add codex. La instalación utiliza el comando propio de la aplicación y deja en paz a los demás servidores. Si ya existe una entrada con el mismo nombre, elimínela de la aplicación antes de ejecutar la configuración nuevamente. El perfil predeterminado ofrece herramientas que escriben. Entonces la configuración le pide que revise los permisos del perfil y lo ejecute nuevamente con --allow-writes. Esa bandera sólo confirma la instalación; no cambia los permisos. Para limitar lo que el agente puede hacer, configure primero el permissions del perfil (abajo).
mcp check no lee mensajes y no inicia sesión en Telegram. Un buen resultado significa que el protocolo de enlace MCP y la lista de herramientas funcionan. No significa que la sesión de la cuenta sea válida. potential_writes cuenta las herramientas que no están marcadas como de solo lectura. Cuando el servidor no se inicia, el error muestra las últimas líneas que escribió en stderr, con su carpeta de inicio, números largos y tokens ocultos. Las aplicaciones del navegador y del teléfono necesitan una conexión remota separada (conectar una aplicación del navegador o del teléfono).
Claude Code, manualmente:
claude mcp add tg -- tg personal mcp serveCon un perfil, pon su nombre primero, como en cualquier comando:
claude mcp add tg-work -- tg work mcp serveUn servidor puede atender varios perfiles. Nómbralos con --profiles, o atiende todos los perfiles con
--profiles all. Cada llamada a una herramienta indica entonces su perfil:
claude mcp add tg -- tg mcp serve --profiles personal,work
claude mcp add tg -- tg mcp serve --profiles alltg mcp serve sin perfil y sin --profiles se niega y muestra tus perfiles: el servidor nunca elige perfiles
por ti. La línea que escribe en stderr al arrancar nombra los perfiles que atiende.
mcp config, mcp revoke, --http y mcp server start|stop|status admiten la misma elección.
Claude Desktop, Cursor y otras aplicaciones: tg imprime la entrada de su archivo de configuración:
tg personal mcp config
tg work mcp config # another profile{
"mcpServers": {
"tg-personal": {
"type": "stdio",
"command": "/usr/bin/node",
"args": ["/usr/lib/node_modules/@wirecat/tg-cli/dist/bin/tg.js", "personal", "mcp", "serve"],
"env": { "XDG_RUNTIME_DIR": "/run/user/1000" }
}
}
}Revise los permisos del perfil antes de conectar a un agente. Luego pegue la entrada en mcpServers en el archivo de configuración de la aplicación. Para Claude Desktop, que es ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y %APPDATA%\Claude\claude_desktop_config.json en Windows; para Cursor, ~/.cursor/mcp.json. El comando no escribe nada por sí mismo.
Las rutas son absolutas porque una aplicación iniciada desde el escritorio no ve el PATH del terminal. En Windows, tg es un archivo tg.cmd, que una aplicación sin shell no puede iniciar. La entrada copia TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE y XDG_RUNTIME_DIR cuando están configurados; nunca TG_API_ID, TG_API_HASH o la sesión.
Si Node proviene de nvm, fnm o Volta, su ruta pertenece a una versión de Node. Ejecute tg personal mcp config nuevamente después de cambiarlo. Ejecutado desde npx, el comando se niega: npx borra su caché y la ruta dejaría de existir.
⚠ TG_CONFIG_DIR, TG_STATE_DIR y TG_CACHE_DIR cambian dónde se busca el inicio de sesión. Si están configurados en el terminal y no para la aplicación MCP, o al revés, el servidor responde "sin sesión" aunque tg funciona en el terminal. Configúrelos iguales en ambos o en ninguno.
⚠ En Linux, las credenciales de la aplicación están en el llavero, al que se accede a través de XDG_RUNTIME_DIR. Una aplicación que inicia servidores con un entorno recortado la omite y cada herramienta responde que el llavero probablemente esté fuera de su alcance. La entrada de tg personal mcp config lo incluye.
Un bot tiene su propio servidor, tg <name> bot mcp serve; consulte el bot para un agente.
Qué puede hacer el agente
El permissions del perfil decide el acceso (qué puede hacer un perfil). deny bloquea un comando, readonly permite solo lecturas y ask o allow permiten la escritura que solicitó el agente. El servidor no muestra formularios de confirmación: configure la aprobación en la aplicación de su agente. En la terminal, un comando en ask aún necesita su confirmación. Con JSON o --no-input no hay pregunta interactiva, por lo que se rechaza la escritura a menos que agregue --yes.
tg agent config set permissions.messages readonly
tg agent config set permissions.messages.send allowAquí agent es el nombre de un perfil. Las escrituras mantienen los límites de destinatarios, los límites por hora y el diario de envío (tg personal sends list). Marcar lectura es una escritura separada, en chats.mark-read. Al eliminar a través de MCP, se eliminan los mensajes solo para usted, como máximo diez a la vez; un agente nunca elimina para todos, y se rechazan los canales y supergrupos que no permiten eliminar solo para uno mismo. --permission key=level endurece un nivel solo para este proceso de servidor; nunca lo afloja.
Herramientas
Cobertura de comandos. Estas herramientas cubren la mayoría de operaciones habituales: mensajes, chats, contactos, adjuntos, conversaciones y estadísticas. La búsqueda devuelve comandos disponibles con parámetros y efectos según el servicio de mensajería y los permisos. Consulta sintaxis y parámetros en la referencia completa. Ejecuta la ruta ofrecida por el catálogo mediante lectura o escritura; acceso a la cuenta e instalación interactiva se realizan en el terminal.
| Herramienta | Qué hace |
|---|---|
tg_tools_search | Encuentra un comando, sus argumentos y sus efectos |
tg_read | Ejecute un comando de lectura que ofrece la búsqueda |
tg_write | Ejecute un comando de escritura que ofrezca la búsqueda |
Ambas herramientas de ejecución toman {command, arguments}. Utilice la ruta de comando que arrojó la búsqueda:
{"command":"stats chats show","arguments":{"chat":"123"}}status lee el estado del perfil a través de tg_read. La búsqueda muestra solo lo que permiten los permisos del perfil y Telegram. Los servidores bot utilizan tg_bot_tools_search, tg_bot_read y tg_bot_write; sus rutas de comando omiten bot.
Las respuestas están estructuradas en JSON: las listas mantienen sus páginas y los identificadores permanecen como cadenas. Una falla es {error:{code,reason,message,details}}; un objetivo que coincide con varios chats trae los candidatos en details.candidates. El servidor compara los argumentos con el esquema del comando y rechaza los campos desconocidos antes de conectarse o actuar. Utilice at_time para programar. Si se desconoce el resultado de una escritura, consulte el diario de envío y Telegram antes de pensar en volver a intentarlo. El texto del mensaje son datos, nunca instrucciones para el agente. Los esquemas, límites y reglas de reintento se encuentran en cómo se comporta tg en los scripts.
Qué está disponible
El descubrimiento de comandos mantiene visibles los comandos denegados por permisos. Tanto el listado completo
como una búsqueda devuelven availability: { available: false, reason, permission } cuando un comando está
bloqueado; los permitidos devuelven availability: { available: true }. El agente puede ver el comando y sus
argumentos sin poder ejecutarlo. La disponibilidad sigue la configuración actual, y cada llamada vuelve a
comprobar los permisos. --help de la CLI y commands --json también conservan los comandos sin importar los
permisos del perfil. Con un perfil indicado muestran además la disponibilidad actual; el descubrimiento sin
perfil no depende de la configuración de la cuenta.
Comandos que el servidor no ofrece
El catálogo incluye comandos de lectura y escritura, sujetos a los permisos del perfil y a las exclusiones siguientes. El acceso de solo lectura se configura mediante esos permisos. Unos pocos comandos no se ofrecen nunca, y los ejecutas en una terminal:
- Inicio de sesión y configuración:
setup,session start|end,complete,mcp config|add|check|revoke,bot auth set|show|remove,bot mcp config. El agente no puede llamarlos o necesitan que estés ante el teclado.mcpybot mcpsolos solo muestran su ayuda. - Eliminar una cuenta:
account removecierra la sesión de un perfil y lo olvida en este ordenador, así que solo tú lo inicias. - Comandos de larga duración:
watch,serveybot watchsiguen hasta que los detienes, y una llamada del agente debe terminar. El propio servidor MCP (mcp serve,bot mcp serve) queda fuera por la misma razón, igual quemcp serverymcp server start|stop|status, que lo ejecutan en segundo plano.
Los comandos store backup|restore, server start|stop|restart, las descargas de modelos,
schedule run|exec, doctor reports create y account sessions end tienen claves de permisos propias, con ask por defecto. Se ofrecen al agente;
la aplicación MCP controla la aprobación. En tg commands --json, un comando que MCP no ofrece lleva
mcp: false, y uno de larga duración lleva un lifetime en su lugar. Las operaciones directas de bot api necesitan un permiso explícito.
Comandos que cambian lo que podrá hacer la siguiente ejecución
config set|unset, recipients add|remove|clear, chats rules set|unset, las reglas y consentimientos de replies,
schedule command|agent|remove, server install|uninstall, skill install,
attachments jobs install|start|stop|uninstall, models keys set|remove, flood clear, upgrade (upgrade --check
solo consulta y no está limitado) y, para bots, recipients add|remove|clear y chats rules set|unset
siguen visibles en el descubrimiento con sus argumentos. Solo se pueden ejecutar cuando el perfil fija
permissions.mcp.authority en allow o ask. El valor por defecto es deny: el descubrimiento los marca
como no disponibles, nombra el permiso y explica el motivo; la llamada se rechaza. De otro modo, un agente limitado a leer
podría habilitar cambios en una ejecución posterior. El agente no puede establecer la clave por sí mismo,
porque también controla config set. Cámbiala desde tu propia
terminal, fuera del agente: un config set ejecutado en la shell de un agente (donde está definida
AI_AGENT, CLAUDECODE u OPENCLAW_SHELL=exec) también se rechaza para esta clave. Hazlo solo en un perfil cuyo
agente sea de confianza:
tg agent config set permissions.mcp.authority allowConsulta los permisos.
Peticiones preparadas y chats mediante @
El servidor ofrece seis peticiones preparadas; en Claude Code son comandos /:
| Aviso | Argumento | Qué hace el agente |
|---|---|---|
catch-up | kind, mode — opcional | llama a tg_read (command: "inbox"); mode es unread (predeterminado), new o una hora; kind selecciona tipos de chat; la lectura de marcado necesita una llamada de herramienta aprobada por separado |
reply | chat | lee el chat, escribe un borrador y lo envía sólo después de tu sí a ese texto |
find | text | busca una persona o palabras y muestra los mensajes alrededor de cada hit; no envía nada |
link-conversations | ninguno | informa el costo y solicita su consentimiento, luego lee lotes, guarda enlaces y reconstruye (abajo) |
review | since, groups — opcional | llama a tg_read (command: "review") una vez y lo clasifica en lo que usted debe, lo que otros deben y lo que necesita ser aclarado; redacta recordatorios, envía uno solo después de tu sí |
open-tasks | chat — opcional | solicita revisión para actualizar tareas, enumera tareas abiertas y sugiere borradores; cierra una tarea sólo después de su aprobación; no envía nada |
reply y review envían a través de tg_write (command: "messages send"). Entonces, donde messages.send es readonly, el agente solo muestra los borradores.
Los chats son recursos tg://chat/<id> — en Claude Code puedes mencionarlos con @. Un recurso es el chat y sus mensajes recientes. La lista proviene de la copia local de tus mensajes y nunca se conecta a Telegram; hasta que se leyó algo, está vacío. Solo se conecta leyendo un chat.
tg_read (command: "messages link") devuelve { item: { ref, url, access, reason } } sin el texto del mensaje. Verifica la cuenta y la audiencia de la misma manera que messages link; un enlace privado no convierte a nadie en miembro. Los puntos de control de la bandeja de entrada y de revisión en MCP están separados de los puntos de control --new del terminal.
Gráficos de estadísticas
tg_read (command: "stats charts") lee las estadísticas de un chat de la copia local y devuelve un chart en JSON. Para una imagen, agregue format: "png": la respuesta es un PNG oscuro más JSON con los datos chart y el tamaño image. Sin format, la respuesta sigue siendo JSON. La herramienta no se conecta a Telegram y no escribe archivos; necesita el permiso messages. Las uniones y salidas (membership) no están disponibles aquí.
Vincular conversaciones
La petición preparada link-conversations permite al agente vincular las respuestas a las conversaciones. El agente primero informa el tamaño del trabajo con tg_read (command: "conversations batches status") y espera su consentimiento. Luego lee lotes con tg_read (command: "conversations batches show"), guarda sus respuestas con tg_write (command: "conversations links add") y reconstruye con tg_write (command: "conversations links rebuild"). tg_write (command: "conversations links clear") elimina las respuestas del agente; reconstruir después de eso también. Para guardar se necesita el permiso conversations.links. Si configura un servicio externo para vectores de búsqueda, la búsqueda MCP también envía el texto de la consulta a ese servicio.
Archivos y mensajes guardados
tg_read (command: "attachments list") muestra las rutas de los archivos guardados y si se extrajo su texto. tg_write (command: "attachments update") guarda el texto que el agente leyó de un archivo. La extracción de texto está sujeta a los permisos de adjuntos del perfil. tg_read con command: "messages context" y arguments: { offline: true } lee solo la copia local.
Cómo se mantiene la conexión
La primera llamada que necesita Telegram se conecta y las siguientes reutilizan la conexión. Se cierra después de 2 minutos sin una llamada y, en cualquier caso, 5 minutos después de su apertura, por lo que una sesión larga de agente nunca lee una instantánea obsoleta. La siguiente llamada se conecta nuevamente. Las llamadas se realizan una a la vez, incluso cuando la aplicación las envía juntas.
A través de stdin y stdout, el servidor se cierra tan pronto como la aplicación cierra stdin y cierra su conexión a Telegram. A través de HTTP se ejecuta hasta Ctrl-C. tg personal mcp revoke finaliza cada inicio de sesión realizado en una aplicación de navegador y mantiene su sesión de Telegram. Consulte conectar un navegador o una aplicación de teléfono.