Unofficial Telegram MCP

MCP local de Telegram MTProto para Codex: solo lectura por defecto, escrituras de texto opcionales con listas de permitidos de chats exactas, y configuración en inglés/ruso para Windows, Linux y macOS. Revisa los términos de la API de Telegram y de IA antes de usar datos reales.

Documentación

Unofficial Telegram MCP

Inglés · Русский

CI Security checks Python 3.11+ MIT license

Configuración · Herramientas de lectura · Escrituras opcionales · Contribuir · Modelo de seguridad

Un servidor local de Model Context Protocol con soporte para Codex y otros clientes MCP compatibles. Sus herramientas encuentran diálogos de Telegram, buscan mensajes, leen el historial y mensajes no leídos, y resumen un período elegido a través de MTProto.

Antes de usar datos reales de Telegram: lea la guía de uso de plataforma y licencias y los Términos de la API de Telegram. La compatibilidad técnica no establece permiso para el procesamiento con IA; las preguntas sobre el uso de la plataforma siguen sin resolverse para esta utilidad. Para una prueba sin cuenta, use la demo ficticia a continuación.

Solo lectura por defecto. Opcionalmente, puede habilitar el envío de texto, la edición de sus propios mensajes y la eliminación de sus propios mensajes en chats explícitamente permitidos. Sin monitoreo en segundo plano ni enviador de notificaciones de escritorio.

Un proyecto comunitario independiente, no afiliado a Telegram ni a OpenAI. Usa su cuenta personal de Telegram, no un token de BotFather.

Contenido

Características

CaracterísticaComportamiento
Siete herramientas de lecturaDiálogos, historial, un mensaje, búsqueda, no leídos, últimos y rangos de tiempo
Tres herramientas de escritura opcionalesEnviar texto plano, editar su propio mensaje, eliminar sus propios mensajes
Control de accesoListas de permitidos separadas para lectura/escritura; la lista de denegados gana
Autorización localTeléfono, código y contraseña 2FA opcional ingresados en su terminal
Sesión localCifrado DPAPI en Windows; archivos solo para el propietario en Linux/macOS
Demo sin cuentaTres chats ficticios y 12 mensajes; sin conexión a Telegram
MCP estándarstdio local y HTTP Streamable autenticado

Devuelve texto de mensajes/subtítulos y metadatos de adjuntos; no descarga medios, no se une a canales, no accede a chats secretos ni proporciona llamadas arbitrarias a la API de Telegram. Leer no marca mensajes como leídos. El modo de escritura agrega solo las tres operaciones documentadas.

1. Instalación: Windows, Linux, macOS

Necesita una cuenta de Telegram existente, acceso a Internet, Git, uv y Python 3.11 o más reciente. Los comandos instalan Python 3.11 a través de uv y crean un .venv aislado; la activación no es necesaria.

Elija un sistema operativo a continuación. Ejecute los comandos en su terminal, una línea a la vez, sin copiar las comillas invertidas de Markdown. Los comandos de instalación descargan herramientas de sus editores; consulte la guía de instalación oficial de uv para alternativas.

Windows — PowerShell

  1. Abra Windows Terminal → PowerShell o Windows PowerShell desde Inicio. Si es necesario, instale Git y uv:
winget install --id Git.Git -e --source winget
winget install --id astral-sh.uv -e --source winget

Si WinGet no está disponible, use el instalador de Git para Windows y el instalador oficial de uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. Cierre y vuelva a abrir PowerShell para actualizar PATH, luego ejecute:
git --version
uv --version
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Projects" | Out-Null
Set-Location "$env:USERPROFILE\Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
Set-Location .\telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if (-not (Test-Path -LiteralPath .env)) { Copy-Item -LiteralPath .env.example -Destination .env }
notepad .env

Está en %USERPROFILE%\Projects\telegram-mcp. Mantenga la terminal abierta. Copie .env.example solo para una instalación nueva; no sobrescriba un .env existente.

Linux — Terminal

  1. Abra una terminal. En Debian/Ubuntu, instale Git y curl si es necesario:
sudo apt-get update
sudo apt-get install -y git curl

En Fedora use sudo dnf install git curl en su lugar; otras distribuciones: use su gestor de paquetes (guía de instalación de Git). Instale uv si es necesario:

curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Cierre y vuelva a abrir la terminal, luego ejecute:
git --version
uv --version
mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
cd telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if [ ! -e .env ]; then cp .env.example .env; fi
nano .env

En nano: Ctrl+O → Enter para guardar, Ctrl+X para salir. Use su editor preferido si nano no está disponible. Está en ~/Projects/telegram-mcp. Cree .env solo una vez; conserve la configuración existente durante las actualizaciones.

macOS — Terminal

  1. Abra Aplicaciones → Utilidades → Terminal. Si Git no está disponible, instale las Herramientas de línea de comandos de Apple y finalice el instalador en pantalla:
xcode-select --install

Instale uv si es necesario:

curl -LsSf https://astral.sh/uv/install.sh | sh

Si ya usa Homebrew, brew install uv es otra opción.

  1. Cierre y vuelva a abrir Terminal, luego ejecute:
git --version
uv --version
mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/daniil-novel/telegram-mcp.git
cd telegram-mcp
uv python install 3.11
uv sync --frozen --python 3.11
if [ ! -e .env ]; then cp .env.example .env; fi
nano .env

En nano: Ctrl+O → Enter para guardar, Ctrl+X para salir. Está en ~/Projects/telegram-mcp. Cree .env solo una vez; conserve la configuración existente durante las actualizaciones.

Pruebe la demo antes de conectar su cuenta

Desde el directorio del repositorio:

uv run --frozen telegram-mcp serve --demo

Este es un servidor stdio, por lo que espera un cliente MCP; no es un terminal interactivo de Telegram. Ctrl+C lo detiene. En la configuración de Codex del paso 5, agregue --demo después de serve para usar herramientas ficticias. La demo no carga su sesión ni se conecta a Telegram. Elimine --demo para su cuenta real. Sus fechas son ejemplos fijos, no mensajes actuales.

2. Obtener credenciales de la API de Telegram

Haga esto en su navegador, no en PowerShell ni en la conversación de IA. Consulte la guía oficial de configuración de aplicaciones de Telegram.

  1. Abra my.telegram.org y verifique el nombre de host.
  2. Ingrese su propio número de teléfono de Telegram en formato internacional, con + y código de país.
  3. Seleccione Siguiente, abra su aplicación oficial de Telegram e ingrese el código de inicio de sesión del sitio web. Siga las instrucciones reales de entrega de Telegram.

Telegram developer website login screen

Pantalla de inicio de sesión del sitio web, sin número de teléfono personal ni código de inicio de sesión.

  1. Abra Herramientas de desarrollo de API. Si ya existe una aplicación, use su api_id y api_hash; Telegram actualmente permite un ID de API por número de teléfono.
  2. Si ve Crear nueva aplicación, complete el formulario. Ejemplo de detalles:
Campo del sitio webQué ingresar
Título de la aplicaciónUnofficial Telegram MCP, o su título descriptivo. Los términos de Telegram requieren "Unofficial" antes de "Telegram" en títulos de aplicaciones de terceros.
Nombre cortoPor ejemplo mytgmcplocal; use letras/dígitos latinos y siga las reglas de longitud y validación del sitio web.
URLSu página pública real de la aplicación si se solicita. La página fuente de este proyecto es https://github.com/daniil-novel/telegram-mcp. No es una devolución de llamada OAuth. Déjelo en blanco si el formulario actual lo permite.
PlataformaEscritorio si se ofrece para un cliente local; de lo contrario, Otro con una descripción. Esto no restringe el repositorio a un solo sistema operativo.
DescripciónPor ejemplo Personal local Telegram client via MTProto. Describa su uso previsto con sinceridad.

Illustrative application creation form with example values

Guía ilustrativa del formulario autenticado. Valores de ejemplo; el sitio web actual puede diferir.

  1. Seleccione Crear aplicación. Copie App api_id y App api_hash en su .env local en el paso 3.

Illustrative location of API ID and API hash, with placeholders

Guía ilustrativa con marcadores de posición, no credenciales reales. No use los valores de API de otra persona.

api_id es numérico; api_hash son 32 caracteres hexadecimales. Estos no son su número de teléfono, código de inicio de sesión, contraseña 2FA, token de bot o clave de OpenAI. Cada usuario obtiene sus propias credenciales; ninguno se distribuye aquí.

Si la creación falla, verifique los requisitos del formulario actual e intente nuevamente más tarde. Este proyecto no puede eludir las restricciones de cuenta de Telegram.

3. Configurar el servidor local

Edite .env en la raíz del repositorio, junto a pyproject.toml. Use la ventana de Notepad/nano abierta en el paso 1. Reemplace ambos marcadores de posición con sus propios valores, sin < ni >:

TELEGRAM_API_ID=<YOUR_NUMERIC_API_ID>
TELEGRAM_API_HASH=<YOUR_32_CHARACTER_API_HASH>
TELEGRAM_SESSION_DIR=
TELEGRAM_ALLOWED_CHAT_IDS=*
TELEGRAM_DENIED_CHAT_IDS=
TELEGRAM_WRITE_ENABLED=false
TELEGRAM_WRITE_ALLOWED_CHAT_IDS=

Guarde como .env, no .env.txt. Mantenga la configuración HTTP de .env.example sin cambios para stdio. Un directorio de sesión vacío usa el valor predeterminado del sistema operativo.

TELEGRAM_ALLOWED_CHAT_IDS=* permite leer todos los diálogos en la nube accesibles para su cuenta. Después de list_dialogs, puede reemplazarlo con IDs numéricos exactos. Una lista de permitidos de lectura vacía deniega todos los chats. Las escrituras permanecen deshabilitadas hasta el paso 7.

Desde la misma terminal en el repositorio, restrinja los permisos de .env:

uv run --frozen telegram-mcp protect-env

Nunca pegue el hash de API, teléfono, código de inicio de sesión, contraseña 2FA, .env o archivos de sesión en chats, problemas o capturas de pantalla. .env es ignorado por Git; esto no protege cargas manuales.

4. Iniciar sesión localmente

Ejecute esto usted mismo en un PowerShell/Terminal interactivo, aún en el repositorio:

uv run --frozen telegram-mcp auth
  1. Teléfono de Telegram (+código de país, oculto): ingrese su número y presione Enter.
  2. Código de inicio de sesión de Telegram (oculto): ingrese el nuevo código enviado por Telegram y presione Enter. Este inicio de sesión es separado de my.telegram.org.
  3. Si se solicita, contraseña 2FA de Telegram (oculta): ingrese su contraseña de Telegram y presione Enter.
  4. Espere Autorizado. Sesión almacenada localmente; no se leyeron ni cambiaron mensajes.

La entrada oculta muestra sin caracteres ni asteriscos mientras escribe. Esto es esperado. La sesión protegida permite que los inicios posteriores funcionen sin otro código. Los códigos y contraseñas 2FA no se guardan. La autorización es un comando local separado; no hay herramienta de inicio de sesión MCP.

Inspeccione/revoca el acceso en Telegram → Configuración → Dispositivos. La sesión usa el nombre de dispositivo del proyecto. Una vez terminada, el servidor no puede iniciar sesión nuevamente.

5. Conectar a Codex

Recomendado: stdio local. Codex inicia el servidor; no se necesita un endpoint público ni token HTTP.

Abra la configuración de usuario de Codex, generalmente %USERPROFILE%\.codex\config.toml en Windows o ~/.codex/config.toml en Linux/macOS. Créela si es necesario. Agregue una tabla, conservando la configuración existente. Reemplace todas las rutas de ejemplo con sus propias rutas absolutas. Las comillas simples de TOML mantienen las barras invertidas de Windows literales.

Configuración de Windows

[mcp_servers.telegram]
command = 'C:\Users\YOUR_USERNAME\Projects\telegram-mcp\.venv\Scripts\python.exe'
args = ['-m', 'telegram_readonly_mcp', '--env-file', 'C:\Users\YOUR_USERNAME\Projects\telegram-mcp\.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

Configuración de Linux

[mcp_servers.telegram]
command = '/home/YOUR_USERNAME/Projects/telegram-mcp/.venv/bin/python'
args = ['-m', 'telegram_readonly_mcp', '--env-file', '/home/YOUR_USERNAME/Projects/telegram-mcp/.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

Configuración de macOS

[mcp_servers.telegram]
command = '/Users/YOUR_USERNAME/Projects/telegram-mcp/.venv/bin/python'
args = ['-m', 'telegram_readonly_mcp', '--env-file', '/Users/YOUR_USERNAME/Projects/telegram-mcp/.env', 'serve']
startup_timeout_sec = 60
tool_timeout_sec = 60

El módulo de compatibilidad telegram_readonly_mcp permanece sin cambios, incluso en modo de escritura. No lo renombre en args. También hay ejemplos de configuración disponibles.

Reinicie/recargue la conexión MCP, o reinicie Codex y abra un nuevo chat si su lista de herramientas está en caché. En Codex CLI, codex mcp list lista los servidores configurados y /mcp muestra las conexiones. Consulte la documentación oficial de MCP de Codex. El .codex/config.toml de un proyecto confiable puede usarse para configuración a nivel de proyecto.

La ruta explícita de Python evita depender de que uv esté en el PATH de la aplicación de escritorio. --env-file es explícito porque Codex puede iniciar el proceso desde otro directorio.

Usuarios de complementos existentes: use el complemento del proyecto o esta entrada independiente. Desactive duplicados. Un complemento puede incluir su propio tiempo de ejecución; actualizar un clon solo no actualiza el complemento instalado.

Primera solicitud:

Use Telegram MCP para listar mis diálogos. Muestre títulos e IDs numéricos de chats. No envíe, edite ni elimine nada.

Debería ver los diálogos reales permitidos. Si source=demo, elimine --demo de la configuración.

6. Leer Telegram

Describa la tarea en lenguaje natural, nombrando el chat y el período:

Encuentre "Project Alpha", luego resuma los mensajes del 1 de octubre al 3 de octubre de 2026 en UTC+03:00. Siga todas las páginas en ese período e incluya IDs de chat e IDs de mensaje para las fuentes.

Busque en ese chat "deadline" y muestre los mensajes coincidentes con fechas.

Muestre mensajes no leídos de mi chat de trabajo sin marcarlos como leídos.

Herramientas de lectura

Todas las herramientas toman params. Los campos desconocidos, limit > 200 y las fechas sin zonas horarias son rechazados.

HerramientaParámetros principalesContinuación
list_dialogsquery?, limit=50cursor=next_cursor
get_chat_historychat_id, limit=50, before_id=0before_id=next_before_id
get_messagechat_id, message_idUn mensaje o null
search_messagesquery, chat_id?, limit=50cursor=next_cursor
get_unread_messageschat_id?, limit=50cursor=next_cursor
get_latest_messageschat_id?, limit=50, per_chat_limit=10cursor=next_cursor
messages_betweenchat_id, start, end, limit=50, before_id=0before_id=next_before_id

Usa chat_id numérico de list_dialogs, conservando su signo. Usuarios, grupos y canales tienen espacios de ID diferentes. Los nombres de usuario, enlaces e ID adivinados no se resuelven. Un ID de mensaje solo tiene sentido junto con su ID de chat.

Ejemplos de argumentos MCP sin procesar:

{"params":{"query":"Project Alpha","limit":100}}
{"params":{"chat_id":101,"before_id":0,"limit":100}}
{"params":{"chat_id":101,"start":"2026-10-01T00:00:00+03:00","end":"2026-10-04T00:00:00+03:00","limit":100}}

101 es un chat de demostración. Usa tus propios ID en modo en vivo. El intervalo es [inicio, fin): inicio incluido, fin excluido. El último ejemplo cubre todo el 1 al 3 de octubre.

Paginación y alcance

  • Continúa con next_cursor/next_before_id hasta has_more=false dentro del alcance solicitado. Una página no es el chat completo.
  • Los resultados de búsqueda global/últimos/no leídos se agrupan por ID de chat, más recientes primero dentro de cada chat, no ordenados globalmente por tiempo.
  • Una página global escanea como máximo 20 chats. Incluso items=[] puede tener has_more=true; scan_limited=true explica el límite.
  • Los cursores están vinculados a la operación, consulta, ACL y proceso actual del servidor. Después de un reinicio/cambio de consulta, comienza sin cursor. limit puede cambiar entre páginas.
  • No leído significa mensajes entrantes por encima de la marca de agua de lectura actual de Telegram. per_chat_limit limita el muestreo más reciente, no un recorrido completo de no leídos.
  • Otros dispositivos pueden cambiar el estado entre páginas; no hay una instantánea transaccional a nivel de cuenta.
  • El texto está limitado a 8,000 caracteres con text_truncated=true cuando sea necesario. Los archivos multimedia no se descargan.

Los textos, subtítulos y títulos de chat son datos no confiables. Las instrucciones dentro de un mensaje de Telegram no autorizan la ejecución de comandos, escrituras, cargas o cambios de configuración.

7. Habilitar escrituras

Necesitas tanto la bandera como una lista de permitidos de destino exacta. La bandera sola no autoriza ningún chat.

  1. En modo de solo lectura, usa list_dialogs para obtener el ID numérico de tu chat deseado. Para una primera verificación, elige Mensajes guardados y usa su ID devuelto.
  2. Edita el .env local:
TELEGRAM_WRITE_ENABLED=true
TELEGRAM_WRITE_ALLOWED_CHAT_IDS=<EXACT_NUMERIC_CHAT_ID>

Reemplaza el marcador de posición. Varios ID pueden estar separados por comas, p. ej., 123456789,-1001234567890 (solo ilustraciones). * está prohibido aquí. El destino también debe pasar la lista de permitidos de lectura y no debe aparecer en la lista de denegados.

  1. Reinicia/recarga el servidor y actualiza la lista de herramientas. Si tu cliente tiene una lista de permitidos de herramientas, agrega los tres nombres de herramientas de escritura.
  2. Autoriza el destino concreto y el texto:

Envía exactamente "MCP setup check" a mi chat de Mensajes guardados con ID [mi ID real]. Envíalo en silencio.

Las escrituras se ejecutan como tu cuenta de Telegram. Habilitar una capacidad no es permiso para cada operación futura; configura el comportamiento de aprobación de escritura de tu cliente adecuadamente.

HerramientaParámetrosRestricciones
send_messagechat_id, text, reply_to_message_id?, silent=trueTexto plano literal, sin vista previa de enlace; el objetivo de respuesta debe existir en el mismo chat
edit_messagechat_id, message_id, textSolo tus propios mensajes de texto plano salientes; los subtítulos multimedia no son editables
delete_messageschat_id, message_ids, revoke=trueSolo tus propios mensajes salientes; 1–100 ID
{"params":{"chat_id":101,"text":"MCP setup check","silent":true}}
{"params":{"chat_id":101,"message_id":13,"text":"Updated text"}}
{"params":{"chat_id":101,"message_ids":[13],"revoke":true}}

El texto de envío/edición es de hasta 4,096 unidades de código UTF-16; Markdown/HTML no se analiza. Los resultados normalmente incluyen un mensaje/ID; una respuesta inusual aceptada de Telegram puede devolver accepted=true con message=null. Inspecciona el historial dirigido para verificarlo; no reenvíes solo para obtener un ID. Telegram aplica sus propios permisos/ventanas de edición. revoke=true solicita la eliminación para los participantes donde se admite y puede ser irreversible; false solicita la eliminación de tu lado donde esté disponible. Los canales y megagrupos requieren revoke=true; este servidor rechaza revoke=false para esos destinos.

No repitas automáticamente una escritura después de un tiempo de espera o respuesta incierta. Puede que ya haya tenido éxito. Inspecciona el destino/historial antes de decidir reintentar.

Para deshabilitar escrituras, establece TELEGRAM_WRITE_ENABLED=false y reinicia. Las herramientas de escritura desaparecen y el guardia RPC rechaza escrituras. Unirse/salir, reacciones, reenvíos, cargas multimedia, cambios de perfil, recibos de lectura y RPC arbitrarios siguen sin estar disponibles.

Referencia de configuración

.env se carga desde el directorio actual del proceso a menos que --env-file esté antes del subcomando. Sin búsqueda hacia arriba. Las variables de entorno del proceso anulan .env. Reinicia para aplicar cambios.

uv run --frozen telegram-mcp --env-file /absolute/path/to/.env protect-env
uv run --frozen telegram-mcp --env-file /absolute/path/to/.env auth
uv run --frozen telegram-mcp --env-file /absolute/path/to/.env serve

En Windows usa una ruta de Windows entre comillas.

VariablePredeterminadoPropósito
TELEGRAM_API_IDVacíoTu ID de API numérico; requerido para en vivo/auth
TELEGRAM_API_HASHVacíoTu hash de API de 32 caracteres; requerido para en vivo/auth
TELEGRAM_SESSION_DIREspecífico del SOCarpeta de sesión externa; en blanco usa el predeterminado
TELEGRAM_ALLOWED_CHAT_IDS*Leer todos los diálogos accesibles, ID exactos separados por comas, o vacío para ninguno
TELEGRAM_DENIED_CHAT_IDSVacíoID exactos denegados tanto para lectura como escritura; denegar gana
TELEGRAM_WRITE_ENABLEDfalseHabilita herramientas/capacidad de escritura
TELEGRAM_WRITE_ALLOWED_CHAT_IDSVacíoDestinos de escritura permitidos exactos; vacío deniega todos; sin comodines
MCP_HTTP_TOKENVacíoSolo HTTP: token ASCII aleatorio separado, ≥32 caracteres, sin espacios en blanco
MCP_ALLOWED_HOSTS127.0.0.1:8765,localhost:8765Hosts permitidos HTTP, sin comodines
MCP_ALLOWED_ORIGINShttp://127.0.0.1:8765,http://localhost:8765Orígenes permitidos HTTP, sin comodines

Privacidad y sesiones

El servidor se ejecuta localmente y contacta a Telegram para las operaciones solicitadas. No contiene un cliente de API de OpenAI y no carga mensajes directamente a un modelo. Las respuestas MCP son visibles para el cliente conectado y su modelo. Limita chats y alcance a material que estés autorizado a compartir.

Las rutas de almacenamiento se conservan de la versión anterior:

SOSesión predeterminadaProtección
Windows%LOCALAPPDATA%\TelegramReadOnlyMCP\session.dpapiCifrado DPAPI del usuario actual y ACL restringida
Linux/macOS$XDG_DATA_HOME/telegram-readonly-mcp/session.secret, predeterminado ~/.local/share/telegram-readonly-mcp/session.secretArchivo 0600, carpeta 0700, verificaciones de propietario; no cifrado en reposo

La autenticación y el servidor deben ejecutarse bajo el mismo usuario del SO. El almacenamiento personalizado debe estar fuera del repositorio; los enlaces simbólicos/junctions se rechazan. No se crea una base de datos de mensajes/contactos. Los archivos de sesión otorgan acceso a la cuenta; no los confirmes ni los transfieras.

Telegram no tiene un alcance de sesión de solo lectura para usuarios. Este código restringe herramientas, verifica ACL y protege clases RPC MTProto exactas, incluidas solicitudes anidadas. Las operaciones desconocidas fallan de forma cerrada. Las anotaciones de herramientas son sugerencias; el código aplica la restricción. La autenticación es separada y no puede enviar/editar/eliminar mensajes.

La ACL filtra la salida MCP y las solicitudes de historial dirigidas. El listado de diálogos de Telegram puede poner metadatos/mensajes últimos de chats denegados en la memoria del backend; se excluyen de la salida. Usa una cuenta separada para un aislamiento de metadatos más estricto.

Revisa los Términos de la API de Telegram y los Términos de licencia de contenido y raspado de IA. Los términos de la API restringen ampliamente el uso de datos de la plataforma para el desarrollo, mejora o implementación de IA. La compatibilidad técnica con MCP no es una afirmación de que Telegram autorice un uso particular de IA. MIT licencia este código, no el contenido de Telegram ni excepciones a los términos de la plataforma.

Lee el modelo de seguridad y sus límites: reglas del repositorio, Bandit, escaneos de dependencias/secretos y CodeQL. SECURITY.md cubre informes de vulnerabilidades privados y revocación. Las verificaciones reducen riesgos conocidos; el contenido permitido sigue siendo visible para el cliente/modelo, y la inyección de prompts no está completamente resuelta.

Notificaciones

Este servidor no se suscribe a actualizaciones de mensajes en segundo plano, no inicia monitoreo, no registra dispositivos push ni emite notificaciones de escritorio. Las lecturas no envían recibos de lectura. Los envíos opcionales usan el silent=true de Telegram por defecto: suprime el sonido de notificación donde se admite, no necesariamente los banners del destinatario.

Un toast etiquetado como ChatGPT no es suficiente para identificar qué integración lo produjo. Este servidor Python no tiene función de notificación de escritorio; el cliente propietario, una pestaña del navegador u otra integración puede producir el toast.

Si usas Telegram Web, abre el sitio real de Telegram Web en el mismo navegador que lo aloja, luego usa el ícono a la izquierda de la dirección → Configuración del sitio / Permisos → Notificaciones → Bloquear. Esto bloquea solo las notificaciones de ese sitio. Consulta las instrucciones oficiales de permisos de Chrome y Edge. Para un navegador en la aplicación, usa sus controles de permisos por sitio si están disponibles; de lo contrario, cierra la pestaña de Telegram Web e identifica la fuente de notificación antes de cambiar configuraciones más amplias. Si un monitor programado de Telegram es responsable, deshabilita ese monitor específico en su cliente propietario. Un cambio en el código del servidor no puede revocar el permiso de notificación de un navegador independiente.

Solución de problemas

ProblemaVerificación
git/uv no reconocidosReabre la terminal después de la instalación; ejecuta comandos de versión.
Credenciales faltantesNombre y ubicación exactos de .env; valores propios sin marcadores de posición; --env-file absoluto correcto.
La autenticación parece ignorar la escrituraLa entrada oculta no muestra nada. Escribe y presiona Enter.
"Usa una terminal interactiva"Ejecuta auth tú mismo en PowerShell/Terminal, fuera de una herramienta MCP.
Telegram rechaza autenticación/formularioVerifica credenciales/nuevo código y validación real del formulario localmente; espera si hay límite de velocidad.
Sesión faltante/expiradaMismo usuario del SO/ruta de sesión; vuelve a ejecutar autenticación local después de la revocación.
Error de permiso de almacenamientoCarpeta local externa normal, sin enlaces simbólicos/junctions; usa protect-env, no permisos públicos.
Conexiones duplicadasConfigura una entrada independiente/plugin; detén instancias obsoletas.
Sin herramientas de escrituraBandera true, reinicio del servidor, actualización de la lista de herramientas del cliente; verifica la lista de permitidos de herramientas/plugin antiguo.
Escritura denegadaID firmado exacto, lista de permitidos de escritura y reglas de lectura permitir/denegar. Lista de escritura vacía no permite ninguna.
Edición/eliminación rechazadaSolo tus mensajes salientes; ID de chat/mensaje correctos y permisos de Telegram.
Página vacía, has_more=trueContinúa con el cursor devuelto; la página puede escanear chats que no coinciden.
FloodWait/límite de velocidadEspera los segundos informados; reduce búsquedas repetidas a chats/fechas seleccionados.
Tiempo de espera de escritura/pérdida de conexiónEl resultado puede ser desconocido. Lee el destino antes de cualquier reintento.
HTTP 401Token de portador coincidente entre servidor/cliente; stdio no necesita ninguno.
Error de Host/Origin HTTPHost/origen explícito que coincida con el puerto de loopback real; sin comodines.
Codex no puede iniciar el procesoRutas absolutas de Python .venv y .env; uv sync --frozen después de la actualización.
Toast de ChatGPT contiene texto de TelegramIdentifica el navegador/integración productor; bloquea el permiso de notificación del sitio de Telegram Web en su propio navegador o deshabilita el monitor específico. Consulta Notificaciones; la captura de pantalla sola no prueba la fuente.

Para ayuda, abre un problema de GitHub con SO, versiones de Python/uv, comando y error redactado. Excluye secretos y contenidos privados de chat.

Actualizaciones y desarrollo

En el repositorio:

git pull --ff-only
uv sync --frozen

Reinicia la conexión. Conserva .env y las sesiones externas. No sobrescribas .env con el ejemplo. La CLI heredada telegram-readonly-mcp y el módulo telegram_readonly_mcp se mantienen.

Comprobaciones de desarrollo sin cuenta:

uv sync --frozen --extra dev
uv run --frozen --extra dev python -m pytest -q
uv run --frozen --extra dev ruff check .
uv run --frozen --extra dev ruff format --check .
uv build

Las pruebas utilizan respuestas sintéticas/falsas; que las pruebas pasen no establece pruebas en vivo de cada cuenta/entorno de Telegram/OS/Docker. Evidencia/límites registrados: VALIDATION.md. Contribuciones: CONTRIBUTING.md. Cambios: CHANGELOG.md.

Contribuye y apoya

Los informes de errores, las correcciones de documentación y las mejoras enfocadas son bienvenidos en inglés o ruso. Fork → rama de características → pull request a main; consulta CONTRIBUTING.md para comandos exactos y comprobaciones sin cuenta. Un fork público no te da acceso de escritura a este repositorio. Reporta vulnerabilidades a través de SECURITY.md, usando ejemplos sintéticos.

Si este proyecto te resulta útil, dale una ⭐ estrella en GitHub. Ayuda a que otras personas descubran la herramienta.

Capa de privacidad planificada

Planificada, no implementada. Investigación verificada el 2026-10-06. Esta versión devuelve datos permitidos de Telegram sin anonimización automática. Aún no existen banderas de privacidad. Esta investigación utilizó documentación pública, sin descargas de modelos, inferencias ni chats privados.

Reemplaza la información identificativa localmente antes de que una respuesta MCP llegue a un modelo en la nube. Los seudónimos conservan significado; el cifrado protege los archivos almacenados. El texto de mensajes cifrados no puede soportar análisis semánticos ordinarios. El contexto aún puede identificar personas después de la seudonimización; mide el riesgo de divulgación usando guías como NIST SP 800-188.

Un proxy de transporte opcional de Telegram cambia el enrutamiento de red; no elimina datos personales de las respuestas MCP.

Pipeline local propuesto

Nuestra recomendación: comienza con un piloto de solo lectura; añade resolución de alias segura para escritura solo después de que las pruebas de aceptación pasen. Estos son requisitos propuestos.

EtapaComportamiento propuesto
Aislar secretosExcluye credenciales de aplicación, sesiones, códigos de inicio de sesión y 2FA de todos los modelos. Apunta a archivos cifrados con AEAD con claves de almacén de SO en todas las plataformas; el texto plano sigue siendo necesario en la memoria del proceso.
Escanear contenidoElimina secretos de mensajes detectados/sospechosos usando reglas deterministas antes de NER/evaluación. Las contraseñas pegadas arbitrariamente pueden permanecer sin detectar.
Minimizar y detectarCubre texto, subtítulos, títulos, nombres, nombres de usuario, enlaces, IDs y metadatos de respuesta/reenvío. Omite campos innecesarios. Usa fragmentos acotados superpuestos y valida estrictamente los intervalos.
Reemplazar localmenteEtiquetas legibles y acotadas a la tarea vinculadas a identificadores locales aleatorios e imposibles de adivinar; mapeo cifrado y con expiración. Mantén los IDs originales locales. Los hashes globales permiten correlación entre tareas.
Evaluador opcionalSin conexión, sin herramientas/red; solo asesoramiento, no puede anular bloqueos. Tiempo de espera de etapa requerida, OOM, salida malformada o entrada no soportada bloquea la exportación.
Controlar respuestasCubre cada herramienta de lectura, página y error. Sin vistas previas crudas ni contenido sensible en registros/diagnósticos.

Más tarde, restaura los alias en un visor local y, después de una aprobación exacta, inmediatamente antes de la operación de Telegram: la aprobación humana de escritura debe vincular el texto restaurado exacto, el destino y la acción mientras se preservan las ACL. Nunca expongas texto plano restaurado a través de resultados MCP, vistas previas, _meta, registros o errores.

La cobertura termina en las nuevas salidas de este servidor. Los datos previamente enviados a la nube, los avisos/historiales de clientes privados y otros conectores requieren controles separados.

Modelos a evaluar

Piloto recomendado en ruso + inglés: reglas deterministas más Horizon, opcionalmente un evaluador local Qwen. La selección está limitada a candidatos revisados.

RolCandidato y hechos upstreamPor qué evaluarlo
Detector localHorizon-Labs/pii-redactor-small: 141M parámetros, Apache-2.0, multilingüeCandidato revisado más pequeño con evidencia publicada en RU/EN; detecta intervalos.
Evaluador local opcionalQwen/Qwen3.5-0.8B: 0.8B parámetros de modelo de lenguaje, Apache-2.0; la tarjeta afirma 201 idiomas/dialectos, documenta servicio solo de textoDestinado a prototipos/investigación; la evaluación fiable de PII sigue sin probarse.
Comparación de detectoresopenai/privacy-filter: Apache-2.0, 1.5B total / 50M parámetros activos, evaluaciones multilingüesDetector de intervalos dedicado con pesos residentes mucho mayores.

Horizon reporta 0.75 de recall de redacción a nivel de carácter en un conjunto de datos externo en ruso: insuficiente por sí solo. Las puntuaciones publicadas usan diferentes conjuntos de datos/definiciones y no pueden establecer una clasificación universal. El recall específico de Telegram y los requisitos de recursos siguen sin medir.

Las dependencias futuras incluyen Transformers/PyTorch u ONNX y un motor evaluador local. Requiere revisiones revisadas y fijadas, hashes SHA-256 de pesos, inferencia sin conexión y sin respaldo automático a la nube, incluso en errores de modelo.

OpenRouter: investigación complementaria solamente

Sensitive Info usa regex/Presidio pero continúa en tiempo de espera de NLP; OpenRouter ya recibe la entrada. Custom Classifiers se ejecutan después de la finalización. Ninguno proporciona nuestro límite local previo a la salida. ZDR limita la retención; los proveedores aún procesan texto plano.

El catálogo en vivo listó google/gemma-3-4b-it en el corte; Qwen3-0.6B/1.7B estaban ausentes a pesar de las páginas de marketing. Evalúa Gemma solo en ejemplos sintéticos/ya saneados. Un evaluador en la nube nunca debe recibir chats crudos para decidir su seguridad de exportación.

Puertas de aceptación antes de que la implementación se lance

  • Mide el recall de intervalos sensibles en RU/EN, el riesgo residual de identificación y la utilidad de resúmenes en fixtures sintéticos de Telegram, incluyendo inflexión, escrituras mixtas, secretos y pistas contextuales.
  • Verifica todos los campos/siete herramientas, páginas, desplazamientos Unicode y expiración. Requiere cero marcadores críticos de fuga observados en pruebas sintéticas de salida/registro/error; aísla estructuralmente los secretos de aplicación.
  • Prueba inyección, tiempo de espera, OOM, salidas malformadas y red denegada; preserva ACL y autorización humana, con cada fallo de procesamiento bloqueando la exportación.
  • Mide CPU/RAM y efectos de cuantización; revisa dependencias, hashes de modelos y ciclo de vida del mapa cifrado. Publica limitaciones: la seudonimización no puede garantizar anonimato.

Uso avanzado y licencia

Consulta guía avanzada de HTTP/Docker/navegador. Comienza con stdio local.

Licencia MIT, copyright 2026 daniil-novel. Conserva los avisos de copyright y permiso en copias o porciones sustanciales. El crédito visible al autor es bienvenido como cortesía; MIT no lo requiere ni hace que una aplicación incorporadora completa sea MIT. Atribución práctica y límites de plataforma: guía de licencias. Las dependencias conservan sus propias licencias: avisos de terceros.

Los nombres/marcas de Telegram y el arte del sitio web conservan los derechos de sus propietarios. El logo oficial de Telegram no es el logo de esta aplicación.