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 · Русский
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
- 1. Instalación: Windows, Linux, macOS
- 2. Obtener credenciales de la API de Telegram
- 3. Configurar el servidor local
- 4. Iniciar sesión localmente
- 5. Conectar a Codex
- 6. Leer Telegram
- 7. Habilitar escrituras
- Referencia de configuración
- Privacidad y sesiones
- Notificaciones
- Solución de problemas
- Actualizaciones y desarrollo
- Contribuir y apoyar
- Capa de privacidad planificada
- Uso avanzado y licencia
Características
| Característica | Comportamiento |
|---|---|
| Siete herramientas de lectura | Diálogos, historial, un mensaje, búsqueda, no leídos, últimos y rangos de tiempo |
| Tres herramientas de escritura opcionales | Enviar texto plano, editar su propio mensaje, eliminar sus propios mensajes |
| Control de acceso | Listas de permitidos separadas para lectura/escritura; la lista de denegados gana |
| Autorización local | Teléfono, código y contraseña 2FA opcional ingresados en su terminal |
| Sesión local | Cifrado DPAPI en Windows; archivos solo para el propietario en Linux/macOS |
| Demo sin cuenta | Tres chats ficticios y 12 mensajes; sin conexión a Telegram |
| MCP estándar | stdio 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
- 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"
- 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
- 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
- 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
- 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.
- 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.
- Abra my.telegram.org y verifique el nombre de host.
- Ingrese su propio número de teléfono de Telegram en formato internacional, con
+y código de país. - 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.

Pantalla de inicio de sesión del sitio web, sin número de teléfono personal ni código de inicio de sesión.
- Abra Herramientas de desarrollo de API. Si ya existe una aplicación, use su
api_idyapi_hash; Telegram actualmente permite un ID de API por número de teléfono. - Si ve Crear nueva aplicación, complete el formulario. Ejemplo de detalles:
| Campo del sitio web | Qué ingresar |
|---|---|
| Título de la aplicación | Unofficial 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 corto | Por ejemplo mytgmcplocal; use letras/dígitos latinos y siga las reglas de longitud y validación del sitio web. |
| URL | Su 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. |
| Plataforma | Escritorio 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ón | Por ejemplo Personal local Telegram client via MTProto. Describa su uso previsto con sinceridad. |

Guía ilustrativa del formulario autenticado. Valores de ejemplo; el sitio web actual puede diferir.
- Seleccione Crear aplicación. Copie App api_id y App api_hash en su
.envlocal en el paso 3.

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
- Teléfono de Telegram (+código de país, oculto): ingrese su número y presione Enter.
- 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. - Si se solicita, contraseña 2FA de Telegram (oculta): ingrese su contraseña de Telegram y presione Enter.
- 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.
| Herramienta | Parámetros principales | Continuación |
|---|---|---|
list_dialogs | query?, limit=50 | cursor=next_cursor |
get_chat_history | chat_id, limit=50, before_id=0 | before_id=next_before_id |
get_message | chat_id, message_id | Un mensaje o null |
search_messages | query, chat_id?, limit=50 | cursor=next_cursor |
get_unread_messages | chat_id?, limit=50 | cursor=next_cursor |
get_latest_messages | chat_id?, limit=50, per_chat_limit=10 | cursor=next_cursor |
messages_between | chat_id, start, end, limit=50, before_id=0 | before_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_idhastahas_more=falsedentro 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 tenerhas_more=true;scan_limited=trueexplica 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.
limitpuede cambiar entre páginas. - No leído significa mensajes entrantes por encima de la marca de agua de lectura actual de Telegram.
per_chat_limitlimita 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=truecuando 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.
- En modo de solo lectura, usa
list_dialogspara obtener el ID numérico de tu chat deseado. Para una primera verificación, elige Mensajes guardados y usa su ID devuelto. - Edita el
.envlocal:
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.
- 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.
- 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.
| Herramienta | Parámetros | Restricciones |
|---|---|---|
send_message | chat_id, text, reply_to_message_id?, silent=true | Texto plano literal, sin vista previa de enlace; el objetivo de respuesta debe existir en el mismo chat |
edit_message | chat_id, message_id, text | Solo tus propios mensajes de texto plano salientes; los subtítulos multimedia no son editables |
delete_messages | chat_id, message_ids, revoke=true | Solo 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.
| Variable | Predeterminado | Propósito |
|---|---|---|
TELEGRAM_API_ID | Vacío | Tu ID de API numérico; requerido para en vivo/auth |
TELEGRAM_API_HASH | Vacío | Tu hash de API de 32 caracteres; requerido para en vivo/auth |
TELEGRAM_SESSION_DIR | Específico del SO | Carpeta 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_IDS | Vacío | ID exactos denegados tanto para lectura como escritura; denegar gana |
TELEGRAM_WRITE_ENABLED | false | Habilita herramientas/capacidad de escritura |
TELEGRAM_WRITE_ALLOWED_CHAT_IDS | Vacío | Destinos de escritura permitidos exactos; vacío deniega todos; sin comodines |
MCP_HTTP_TOKEN | Vacío | Solo HTTP: token ASCII aleatorio separado, ≥32 caracteres, sin espacios en blanco |
MCP_ALLOWED_HOSTS | 127.0.0.1:8765,localhost:8765 | Hosts permitidos HTTP, sin comodines |
MCP_ALLOWED_ORIGINS | http://127.0.0.1:8765,http://localhost:8765 | Orí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:
| SO | Sesión predeterminada | Protección |
|---|---|---|
| Windows | %LOCALAPPDATA%\TelegramReadOnlyMCP\session.dpapi | Cifrado DPAPI del usuario actual y ACL restringida |
| Linux/macOS | $XDG_DATA_HOME/telegram-readonly-mcp/session.secret, predeterminado ~/.local/share/telegram-readonly-mcp/session.secret | Archivo 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
| Problema | Verificación |
|---|---|
git/uv no reconocidos | Reabre la terminal después de la instalación; ejecuta comandos de versión. |
| Credenciales faltantes | Nombre y ubicación exactos de .env; valores propios sin marcadores de posición; --env-file absoluto correcto. |
| La autenticación parece ignorar la escritura | La 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/formulario | Verifica credenciales/nuevo código y validación real del formulario localmente; espera si hay límite de velocidad. |
| Sesión faltante/expirada | Mismo usuario del SO/ruta de sesión; vuelve a ejecutar autenticación local después de la revocación. |
| Error de permiso de almacenamiento | Carpeta local externa normal, sin enlaces simbólicos/junctions; usa protect-env, no permisos públicos. |
| Conexiones duplicadas | Configura una entrada independiente/plugin; detén instancias obsoletas. |
| Sin herramientas de escritura | Bandera true, reinicio del servidor, actualización de la lista de herramientas del cliente; verifica la lista de permitidos de herramientas/plugin antiguo. |
| Escritura denegada | ID 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 rechazada | Solo tus mensajes salientes; ID de chat/mensaje correctos y permisos de Telegram. |
Página vacía, has_more=true | Continúa con el cursor devuelto; la página puede escanear chats que no coinciden. |
| FloodWait/límite de velocidad | Espera los segundos informados; reduce búsquedas repetidas a chats/fechas seleccionados. |
| Tiempo de espera de escritura/pérdida de conexión | El resultado puede ser desconocido. Lee el destino antes de cualquier reintento. |
| HTTP 401 | Token de portador coincidente entre servidor/cliente; stdio no necesita ninguno. |
| Error de Host/Origin HTTP | Host/origen explícito que coincida con el puerto de loopback real; sin comodines. |
| Codex no puede iniciar el proceso | Rutas absolutas de Python .venv y .env; uv sync --frozen después de la actualización. |
| Toast de ChatGPT contiene texto de Telegram | Identifica 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.
| Etapa | Comportamiento propuesto |
|---|---|
| Aislar secretos | Excluye 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 contenido | Elimina secretos de mensajes detectados/sospechosos usando reglas deterministas antes de NER/evaluación. Las contraseñas pegadas arbitrariamente pueden permanecer sin detectar. |
| Minimizar y detectar | Cubre 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 localmente | Etiquetas 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 opcional | Sin 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 respuestas | Cubre 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.
| Rol | Candidato y hechos upstream | Por qué evaluarlo |
|---|---|---|
| Detector local | Horizon-Labs/pii-redactor-small: 141M parámetros, Apache-2.0, multilingüe | Candidato revisado más pequeño con evidencia publicada en RU/EN; detecta intervalos. |
| Evaluador local opcional | Qwen/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 texto | Destinado a prototipos/investigación; la evaluación fiable de PII sigue sin probarse. |
| Comparación de detectores | openai/privacy-filter: Apache-2.0, 1.5B total / 50M parámetros activos, evaluaciones multilingües | Detector 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.