tg-mcp

Servidor MCP sobre una cuenta personal de Telegram: 79 herramientas, MTProto, no Bot API.

Inglés

Qué es. tg-mcp da a un cliente MCP — Claude Code, Claude Desktop o cualquier otra cosa que hable MCP — acceso a tu cuenta personal de Telegram: leer cualquier chat, buscar en todo el historial, ver fotos, escuchar mensajes de voz, enviar como tú, gestionar grupos y foros. Habla MTProto a través de Telethon, no el Bot API, por lo que ve la cuenta completa, no solo los mensajes dirigidos a un bot.

Cómo funciona. Un demonio posee la sesión de Telegram y hace todo el trabajo; el servidor MCP es un proceso stdio delgado que reenvía las llamadas a través de un socket unix. El mismo demonio también funciona cuando no hay ningún agente ejecutándose: alertas de mensajes entrantes a tu propio bot, un resumen programado, filtros de bandeja de entrada y recordatorios. Debido a ese socket unix, los sistemas compatibles son macOS y Linux; en Windows usa WSL o Docker.

Inicio rápido (necesita Python 3.11+ y uv):

git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg init      # one wizard: keys, login, bot, daemon, MCP registration, subagents

tg init solo pregunta por lo que falta, así que volver a ejecutarlo es seguro y sirve también como comando de reparación. Solo las claves API y el propio inicio de sesión son obligatorios; todo lo demás se omite con Enter, y el asistente indica qué deja de funcionar sin cada elemento. El código de inicio de sesión y la contraseña 2FA los escribes tú y nunca se almacenan. uv run tg doctor imprime el estado de una instalación existente.

Antes de ejecutarlo. Esta es una herramienta personal, no un servicio alojado, y contiene una cuenta real. data/session.session es acceso total a esa cuenta sin contraseña y sin 2FA; el índice local y los dosieres por chat guardan el texto de los mensajes en disco; la función de dosieres envía el contenido del chat a un modelo externo. Lee primero SECURITY.md; es breve.

Cuánto cuesta. Nada por defecto. Dos funciones opcionales pueden costar: los dosieres por chat llaman a un modelo externo, facturado por token (desactivado hasta que los actives, y con un límite por hora cuando lo hagas); y la transcripción de Groq solo es gratuita dentro de sus límites de uso. La transcripción propia de Telegram requiere Premium, y el modelo local Whisper cuesta disco y CPU, no dinero.

Cuando algo falle, empieza con uv run tg doctor y docs/troubleshooting.md.

El resto de la documentación está en ruso: docs/tools.md (cada herramienta), docs/architecture.md, docs/configuration.md, docs/mcp.md, docs/troubleshooting.md, docs/security.md. Licencia MIT.

Related MCP server: mcp-telegram

Qué es

Un wrapper sobre la cuenta personal de Telegram que se la entrega al agente como un conjunto de herramientas MCP. Funciona sobre MTProto (Telethon), no sobre Bot API, por lo que se ve toda la cuenta, no solo lo que le escribieron al bot. Es una herramienta personal para una sola cuenta y un solo propietario, no un servicio: mantiene una sesión viva de Telegram en tu máquina y escribe a personas reales en tu nombre.

La diferencia con los wrappers sobre Bot API es fundamental, no cuantitativa. El bot solo ve los mensajes que le dirigen, no puede leer la conversación con una persona, no tiene historial y no existe hasta que alguien pulsa Start. Aquí el agente tiene el mismo acceso que tú en la aplicación: todos los diálogos, búsqueda en toda la correspondencia, adjuntos, carpetas, borradores, envío en tu nombre. El precio de esto es la sección «Riesgos» más abajo, y hay que leerla antes de ejecutar, no después.

Qué puede hacer

El agente no solo lee la correspondencia, sino que también mira imágenes (tg_view entrega la imagen en sí) y escucha audio: los mensajes de voz, los videomensajes, la música y el vídeo se transcriben con la transcripción integrada de Telegram, a través de Groq Whisper o con un modelo local. Los posts largos los resume el propio Telegram (tg_summarize), las historias se leen sin dejar rastro, y tg_wait y tg_ask permiten al agente esperar el mensaje adecuado o pedir permiso al propietario directamente en el bot.

El análisis de los mensajes entrantes no se limita a lo no leído: tg_pending muestra conversaciones truncadas: a quién no se respondió y quién no respondió, incluido lo leído y olvidado, que ya no está en el contador de no leídos. tg_person reúne un dosier sobre una persona con una sola llamada: perfil, banderas, chats comunes, posición en el ranking de interlocutores, historial de correspondencia personal. tg_memory mantiene un dosier permanente sobre un chat para que una conversación desconocida no empiece con mil mensajes de historial.

El demonio también hace cosas para las que no hace falta ejecutar Claude: alertas de mensajes importantes en tu bot, un resumen programado (digest_at), filtros de bandeja de entrada (marcar como leído, archivar, silenciar, mover a carpeta, a Favoritos) y recordatorios que sobreviven al reinicio. No hay respuestas automáticas entre las acciones de los filtros a propósito: una regla funciona sin supervisión y no debe poder escribir a una persona ajena.

Para los chats nombrados por el propietario se levanta un índice local de texto completo (tg_index, sqlite + FTS5): entonces tg_search(engine="local") busca al instante y hace lo que la búsqueda del servidor no sabe hacer en absoluto: filtro por autor, corte de «todo de tal persona en un período», clasificación por relevancia y resaltado de coincidencias.

La referencia completa es docs/tools.md.

Qué hay dentro

MCP-клиент (Claude Code, Claude Desktop, любой другой)
        │  stdio
        ▼
tgagent.mcp_server ──unix socket──▶ tgagent.daemon ──MTProto──▶ Telegram
   79 инструментов    /data/daemon.sock      │
                                             ├─ watcher: входящие → фильтры → алерт
                                             ├─ дайджест по расписанию
                                             ├─ напоминания и ожидание
                                             └─ Bot API ──▶ твой бот ──▶ ты

El núcleo es tgagent/core.py: una clase TelegramService, todas las operaciones con la cuenta y todos los salvaguardas. Todo lo demás es transporte a su alrededor. Más detalles: docs/architecture.md.

Inicio rápido

Se necesita Python 3.11 o superior y uv. El listón lo pone una sola cosa: datetime.UTC, un alias de 3.11; no hay nada de 3.12 ni 3.13 en el código. El sistema es macOS o Linux: el servidor MCP habla con el demonio a través de un socket unix, por lo que Windows no es compatible (funciona en WSL o Docker).

El directorio puede ser cualquiera: el proyecto toma las rutas desde sí mismo, y todos los comandos que imprime ya contienen la ruta real hasta esa copia.

git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg init

tg init es un asistente que lleva la instalación a un estado funcional: claves de la aplicación, inicio de sesión en la cuenta, bot de notificaciones, demonio, registro del servidor MCP en Claude Code y subagentes en ~/.claude/agents. Cada paso explica para qué sirve y qué dejará de funcionar sin él.

Conviene conocer de antemano tres propiedades del asistente:

• Solo son obligatorios api_id/api_hash y el inicio de sesión. El bot, las claves de los modelos, la transcripción local y el arranque automático se omiten con Enter.

• El código de Telegram y la contraseña 2FA en la nube los introduces tú. El asistente no los solicita, no los rellena ni los almacena; pasa ese paso a tg login.

• Se puede volver a ejecutar sin riesgo. El asistente primero mira lo que ya está hecho y solo hace lo que falta, por lo que también sirve como «arréglame la instalación».

Lo que hará falta por el camino: una aplicación en my.telegram.org → API development tools (de ahí api_id y api_hash; sin ellos solo está disponible Bot API, es decir, no se ven tus propios chats) y, si necesitas alertas, un bot separado de @BotFather: no se puede reutilizar uno existente, porque sus mensajes se convertirán en entrantes para ti y provocarán alerta sobre alerta.

Al final, el asistente imprime tg capabilities: qué está disponible, qué está bloqueado y por qué exactamente. El estado de una instalación ya existente lo analiza uv run tg doctor: qué hay instalado, qué se está ejecutando, dónde están los archivos y qué permisos tienen, si el demonio responde, si MCP está registrado, si los subagentes coinciden con el repositorio. En su salida no hay claves, teléfono ni nombre de la cuenta, por lo que se puede adjuntar entera a un issue. Si después de eso algo sigue sin funcionar, docs/troubleshooting.md: allí se enumeran las averías frecuentes tal como se ven desde fuera.

Si se prefiere paso a paso

El asistente no hace nada por sí mismo: llama a los mismos comandos, y cualquiera de ellos se puede ejecutar por separado:

cp .env.example .env && chmod 600 .env
uv run tg setup        # api_id/api_hash и токен бота, скрытым вводом
uv run tg login        # телефон, код из Telegram, облачный пароль при 2FA
uv run tg link-bot     # нажми Start в чате с ботом, команда запомнит твой chat_id
uv run tg daemon start # демон владеет сессией; без него инструменты не работают
uv run tg status       # что настроено, что нет, живой ли демон
claude mcp add -s user telegram -- uv --directory "$PWD" run tg-mcp
cp agents/*.md ~/.claude/agents/

Luego, docs/mcp.md: ámbito de aplicación, Claude Desktop, subagentes listos, diagnóstico. La configuración de alertas, filtros y límites está en docs/configuration.md.

Docker

cp .env.example .env && chmod 600 .env   # заполни TG_API_ID / TG_API_HASH / TG_BOT_TOKEN
docker compose build
docker compose run --rm tgagent tg login # логин интерактивно, сессия ляжет в ./data
docker compose up -d
claude mcp add telegram -- docker exec -i tgagent tg-mcp

Los detalles, incluido por qué MCP se ejecuta dentro del contenedor y no en el host, están en docs/docker.md.

Cuánto cuesta

El agente en sí es gratuito y, en su forma básica, no hay a quién pagar: MTProto, bot de notificaciones, búsqueda en el servidor, índice local, alertas, resumen, filtros y recordatorios no cuestan dinero. La factura puede aparecer exactamente en dos lugares, y ambos requieren una clave que por defecto no existe:

• Dosieres de chats (tg_memory) acude a un modelo externo y se paga por tokens; por defecto, gpt-4o-mini con la clave OPENAI_API_KEY. Es lo único que gasta dinero por sí solo, sin Claude en ejecución, y por eso está limitado de tres maneras: sin clave, la herramienta se niega; la actualización automática está desactivada; y, al activarla, se topa con un techo por hora (memory_max_per_hour, por defecto 10). TG_MEMORY_BASE_URL desvía las llamadas a cualquier servicio compatible, incluido local; entonces es gratuito.

• Transcripción de audio (tg_transcribe): tres motores con precios distintos. La integrada en Telegram se calcula en sus servidores y está realmente disponible con Premium (sin suscripción, Telegram da una pequeña cuota gratuita). En Groq, el nivel gratuito está limitado por el número de solicitudes; por encima, hay un plan de pago. El modelo local no cuesta dinero: el precio está en los 1,5 GB de pesos y en el tiempo de cómputo.

Los tokens del propio Claude no son relevantes aquí: los cuenta tu cliente, no el agente. Las claves y los límites están en docs/configuration.md.

Riesgos

Léelo antes de ejecutar, no después. Completo en SECURITY.md y docs/security.md.

• data/session.session es la entrada a la cuenta sin contraseña y sin 2FA. Un archivo copiado equivale a una cuenta robada. Está protegido por .gitignore y .dockerignore, pero de las copias de seguridad y de la sincronización del directorio en la nube respondes tú.

• El agente escribe a personas reales. Con TG_ALLOW_WRITE=1 envía mensajes en tu nombre, y el destinatario no sabe que no lo escribiste tú.

• El índice local y los dosieres guardan la correspondencia en el disco, y la actualización del dosier la envía a un modelo externo. Ni lo uno ni lo otro se activa solo: hay que nombrar el chat explícitamente, y cada una de esas llamadas entra en la auditoría.

• Las inyecciones de prompt son un problema abierto. Los mensajes ajenos se declaran datos en los prompts de los subagentes y nunca los interpreta el código, pero no se considera una garantía: lo respaldan límites, auditoría y un conjunto reducido de herramientas en el observador barato.

• En el chat hay otra persona que no ha dado su consentimiento a todo esto.

Salvaguardas

• 60 mensajes por hora, máximo 15 chats distintos por hora (anti-envío masivo), 50 eliminaciones por hora

• TG_ALLOW_WRITE=0 desactiva por completo la escritura

• confirm_writes: modo intermedio: cada acción de escritura pregunta al propietario en el bot; el silencio se considera rechazo. Solo se modifica mediante archivo: el agente no debe poder quitarse la restricción

• cada acción de escritura se registra en data/actions.jsonl y la lee tg_actions

• los filtros de entrantes no pueden enviar a personas reales: la lista de acciones está cerrada

• un nombre de chat ambiguo no se adivina: la herramienta devuelve una lista de candidatos

• FloodWait de Telegram se devuelve como un error comprensible, no como un fallo

Comandos

uv run tg init                        # мастер установки, он же «почини установку»
uv run tg doctor                      # диагностика: что стоит, что сломано, что делать
uv run tg status                      # что настроено, что нет, состояние демона
uv run tg capabilities                # что доступно, что нет и что с этим делать
uv run tg setup                       # ключи и токен бота
uv run tg login                       # вход целиком
uv run tg send-code +7XXXXXXXXXX      # то же в три шага, без интерактива
uv run tg sign-in --code 12345
uv run tg password                    # облачный пароль 2FA, только с живого tty
uv run tg link-bot                    # привязать chat_id для алертов
uv run tg accounts                    # какие аккаунты залогинены и какой по умолчанию
uv run tg login --account work        # добавить второй аккаунт
uv run tg accounts --default work     # сменить аккаунт по умолчанию навсегда
uv sync --extra local-whisper         # локальная расшифровка звука (опционально)
uv run tg daemon start|run|stop|restart|status|logs
uv run tg call dialogs '{"limit": 5}' # дёрнуть метод демона мимо MCP
uv run tg logout                      # отозвать сессию и стереть файлы

Documentación

Participación y licencia

Se aceptan correcciones: cómo levantar el entorno, qué ejecutar antes del PR y por qué la funcionalidad se añade en tres lugares a la vez, está escrito en CONTRIBUTING.md. Sobre vulnerabilidades — SECURITY.md, no es necesario abrir un issue público.

MIT, © 2026 Roman Akramov.