telegram-mcp

Le da a Claude la imagen más reciente de un grupo de Telegram.

Las capturas de pantalla las publica un bot, y la API de Bot de Telegram nunca devuelve los mensajes del propio bot, así que esto lee el grupo con una cuenta de usuario a través de MTProto (Telethon). Esa es la única forma de ver esas fotos.

Configuración (una vez)

1. Obtén un api id y un hash desde https://my.telegram.org → API development tools.

2. cp .env.example .env y rellena TELEGRAM_API_ID, TELEGRAM_API_HASH y TELEGRAM_CHAT_ID (el id numérico del grupo, negativo).

3. Crea el entorno:

   python -m venv .venv
   .venv\Scripts\pip install -e .[dev]

4. Inicia sesión — en una terminal, no a través de Claude:

   .venv\Scripts\telegram-mcp-login

   Te pide tu número de teléfono, el código que Telegram envía y tu contraseña de verificación en dos pasos si la tienes, y luego escribe session/telegram.session.

   También lista tus diálogos una vez y te devuelve el nombre del grupo. El listado es lo que permite que la sesión resuelva un supergrupo más tarde — Telegram convierte un grupo en supergrupo en cuanto un bot se une a él — y el nombre es tu confirmación de que TELEGRAM_CHAT_ID apunta a donde crees. Si no puede encontrar el grupo, lo dice y sale con un código de error distinto de cero.

Related MCP server: telegram-user-mcp

Instalar en Claude

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

Ámbito de usuario, así que todos los proyectos lo tienen.

Herramientas

• get_latest_image() — la foto más reciente del grupo, mirando hacia atrás 200 mensajes.

• wait_for_next_image(timeout_seconds=120) — se bloquea hasta que llega una foto más reciente que el momento de la llamada. Esperar no cuesta tokens; el proceso queda inactivo en un socket. Limitado a 1–240 s para mantenerse dentro del tiempo de espera de la herramienta del cliente MCP.

Ambas devuelven la imagen (JPEG, lado largo ≤1568 px) más una línea de texto: primero la ruta al original sin tocar, luego el id del mensaje, la marca de tiempo, el remitente y el pie de foto, entre comillas. Recorta ese original cuando la reducción de escala pierde letra pequeña.

Solo un proceso puede tener la sesión a la vez. Si una segunda sesión de Claude Code llama a una herramienta mientras la primera está en medio de una llamada, se le dice que lo intente de nuevo en un momento, en lugar de darle un error de SQLite.

Pruebas

.venv\Scripts\python -m pytest

Sin red, sin necesidad de cuenta de Telegram — Telethon está simulado en todo.

Seguridad

session/telegram.session es un inicio de sesión completo en tu cuenta de Telegram. Está en gitignore y nunca sale de esta máquina. Cualquiera que tenga ese archivo puede leer tus mensajes; bórralo y vuelve a ejecutar el inicio de sesión si sospechas que se ha copiado. Las credenciales viven solo en .env — nunca en documentos, prompts o tickets.