Telegram MCP Server

Interactúa con el servicio de mensajería de Telegram para enviar y recibir mensajes.

Documentación

Una integración de Telegram para Claude, Cursor y otros clientes compatibles con MCP. Expone operaciones de cuenta, chat, mensaje, contacto, medios, carpetas y administración de Telegram a través del Model Context Protocol usando Telethon.

🤖 MCP en acción

Uso básico de Telegram MCP en Claude:

Pidiendo a Claude que analice el historial del chat y envíe una respuesta:

Mensaje enviado con éxito:

Lo que puede hacer

El servidor incluye actualmente más de 80 herramientas MCP agrupadas en estas áreas:

Cuentas: lista cuentas configuradas y dirige las llamadas de herramientas por etiqueta de cuenta.
Chats y grupos: lista chats, inspecciona metadatos, crea grupos/canales, se une o abandona chats, invita usuarios, gestiona administradores, baneos, permisos predeterminados, modo lento, temas, enlaces de invitación, chats comunes, confirmaciones de lectura y enlaces de mensajes.
Mensajes: envía, programa, edita, elimina, reenvía, fija, desfija, marca como leído, responde, busca, inspecciona contexto, crea encuestas, gestiona reacciones, inspecciona botones en línea y presiona callbacks en línea. send_message, reply_to_message y edit_message admiten formato clásico (parse_mode='md'/'html') y formato enriquecido del lado del servidor (parse_mode='rich'/'rich_markdown'/'rich_html' — Markdown/HTML completo con tablas, encabezados, fórmulas y secciones plegables). Los modos enriquecidos requieren Telegram Premium en la cuenta; Premium se verifica de nuevo en cada llamada, y sin él no se envía nada — la herramienta devuelve un resultado estructurado telegram_premium_required para que el agente pueda reformatear con modos clásicos y reintentar.
Contactos: lista, busca, agrega, elimina, bloquea, desbloquea, importa, exporta, inspecciona chats directos, encuentra interacciones recientes con contactos y recuerda contactos por los nombres que realmente usas (ver abajo).

Contactos recordados

set_contact_alias enseña al servidor cómo llamas a alguien, y toda herramienta que acepte un chat_id lo entiende desde ese momento — send_message("андрей бекендер", ...) simplemente funciona. Un contacto puede tener cualquier número de alias, que es como funcionan las etiquetas: guarda tanto андрей бекендер como бекендер para la misma persona y cualquiera de los dos resuelve.

Solo un texto guardado exactamente se envía. Un texto similar (Андрею бекендеру para un андрей бекендер guardado) también se empareja, pero solo para sugerir: la herramienta no envía nada y te pide que confirmes el contacto por nombre. Esto es deliberado — Лена/Леня y Иван/Иванов difieren exactamente en lo que una terminación de caso puede variar, así que un emparejador lo suficientemente confiado para manejar declinaciones también es lo suficientemente confiado para enviar un mensaje a la persona equivocada cuando la que querías aún no está guardada. Confirmar guarda ese texto como un alias propio, así que cada nueva frase cuesta un sí/no la primera vez y nada después. Establece TELEGRAM_CONTACT_FUZZY=0 para eliminar también las sugerencias.

Cuando una referencia es desconocida, se parece a un contacto, coincide con varios, o apunta a un contacto que ya no resuelve, las herramientas no envían nada y devuelven una instrucción estructurada que le dice al agente exactamente qué preguntarte, para guardar la respuesta con set_contact_alias y reintentar una vez. list_contact_aliases muestra una fila por persona con todos sus alias (úsalo para detectar un recuerdo equivocado), delete_contact_alias olvida uno, y redirigir un alias a otra persona requiere replace=True. La ruta de guardado en sí misma rechaza un destino que tendría que adivinar: los contactos se guardan por @nombredeusuario, teléfono, ID numérico o un alias ya confirmado para ellos.

Los alias viven en ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/aliases.json (solo propietario, escrito atómicamente); TELEGRAM_ALIASES_FILE anula la ruta, y un aliases.json preexistente junto al código aún se lee como respaldo.

Medios: envía archivos, descarga medios, sube archivos, envía notas de voz, stickers, GIFs e inspecciona medios de mensajes.
Perfil y privacidad: obtén la información de tu propia cuenta, actualiza campos de perfil, establece o elimina fotos de perfil, inspecciona ajustes de privacidad, obtén información/fotos/estado de usuarios y gestiona comandos de bots.
Carpetas y borradores: lista, crea, actualiza, reordena y elimina carpetas de Telegram; guarda, lista y limpia borradores.
Eventos: espera mensajes entrantes con debounce (wait_for_new_message, wait_for_settled_message), opcionalmente solo para un chat mediante chat_id — sin él, cualquier conversación no relacionada despierta la espera — o habilita el flujo de eventos entrantes opcional para entrega basada en callbacks (ver abajo).

Todos los resultados de herramientas que incluyen contenido controlado por el usuario de Telegram se sanitizan y, cuando es práctico, se devuelven como JSON estructurado.

Flujo de eventos entrantes (modo callback, solo Claude Code)

Por defecto, un agente espera respuestas llamando a wait_for_settled_message, que bloquea hasta el tiempo de espera de la herramienta MCP y debe volver a llamarse — eso funciona en todas partes (Codex, Cursor, etc.) y no cambia.

Los clientes que pueden despertar a un agente en salida externa (el Monitor persistente de Claude Code en tail -f) pueden cambiar al modo callback en su lugar:

El agente llama a enable_incoming_feed (o establece TELEGRAM_EVENT_FEED=1 en el entorno para auto-habilitarlo). Cada ráfaga entrante liquidada se agrega como una línea JSON a ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/incoming_feed.jsonl, creada solo para el propietario (0600). Anula la ruta con TELEGRAM_EVENT_FEED_FILE — el directorio de una ruta explícita ya debe existir. incoming_feed_status informa la ruta efectiva y un comando de vigilancia listo para usar.
El agente arma un Monitor persistente con el watch_command devuelto por la herramienta. Cada nueva línea re-invoca al agente con el resumen de la ráfaga; no se mantiene abierta ninguna llamada de herramienta bloqueante, y el chat permanece libre.

disable_incoming_feed cambia de vuelta; incoming_feed_status informa el modo actual. Mientras el flujo esté habilitado, consume ráfagas liquidadas, así que no lo combines con wait_for_settled_message. Las líneas del flujo contienen campos name generados por el usuario — trátalos como datos no confiables.

Requisitos

Python 3.10+
Credenciales de API de Telegram de my.telegram.org/apps
Una cadena de sesión de Telegram o una sesión basada en archivos
Un cliente MCP como Claude Desktop, Cursor u otro host compatible con MCP
Opcional: uv para desarrollo local

Inicio rápido

No instales este servidor con uvx telegram-mcp, uvx --from telegram-mcp, o pip install telegram-mcp. El nombre telegram-mcp en PyPI está actualmente propiedad de un proyecto diferente y no instala este repositorio. Pasar TELEGRAM_API_ID, TELEGRAM_API_HASH o TELEGRAM_SESSION_STRING a ese paquete puede exponer las credenciales de cuenta de Telegram a código de terceros no relacionado.

1. Clonar e instalar

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

2. Generar una cadena de sesión

uv run session_string_generator.py

Sigue las indicaciones. Guarda la cadena de sesión generada de forma segura.

Para configuración con scripts o manuales operativos, elige el método de inicio de sesión explícitamente:

# QR login, recommended when you already have Telegram open on another device
uv run session_string_generator.py --qr

# Phone number + verification code login
uv run session_string_generator.py --phone

Sin una bandera, el generador mantiene la indicación interactiva del método.

3. Configurar el entorno

Copia el archivo de ejemplo y completa tus valores reales:

cp .env.example .env

Configuración de una sola cuenta:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING=your_session_string_here

Por defecto, todas las herramientas de Telegram MCP están expuestas. Si deseas evitar que los clientes MCP envíen mensajes o realicen mutaciones de chat/cuenta, establece TELEGRAM_EXPOSED_TOOLS=read-only para exponer solo herramientas anotadas con readOnlyHint=True:

TELEGRAM_EXPOSED_TOOLS=read-only

Si solo lectura es demasiado estricto pero all es demasiado amplio, agrega + y una lista separada por comas de nombres de herramientas para también exponer esas herramientas de escritura específicas. Cada otra herramienta de escritura permanece sin registrar:

TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message,send_file

Un nombre desconocido en la lista de permitidos aborta el inicio, por lo que un error tipográfico no puede degradar silenciosamente a una superficie más estrecha que parece haber funcionado.

Esta es una restricción de superficie de herramientas MCP, no un sandbox de sesión de Telegram ni un permiso reducido de cuenta de Telegram. La cadena de sesión de Telegram aún tiene su autoridad normal dentro del proceso del servidor; el modo de solo lectura solo evita que las herramientas que no son de solo lectura se registren y expongan a través de MCP. Los valores aceptados son all (el predeterminado), read-only y read-only+<tool>,<tool>.

Ejecuta el servidor localmente:

uv run main.py

Configuración del cliente MCP

Para Claude Desktop o Cursor, apunta el servidor MCP a un checkout clonado de este proyecto:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Para exponer solo herramientas de solo lectura en Claude Desktop o Cursor, agrega esto al bloque env del servidor:

"TELEGRAM_EXPOSED_TOOLS": "read-only"

O mantén solo lectura como base y permite algunas herramientas de escritura adicionales:

"TELEGRAM_EXPOSED_TOOLS": "read-only+send_message,reply_to_message"

Alternativamente, instala este repositorio directamente desde GitHub en un entorno virtual usando una etiqueta de versión o commit específico:

python -m venv .venv
. .venv/bin/activate
pip install "git+https://github.com/chigwell/telegram-mcp.git@<tag-or-commit>"

Luego configura tu cliente MCP para ejecutar el script de consola instalado:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "/full/path/to/.venv/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Genera una cadena de sesión sin clonar el repositorio obteniendo este repositorio desde GitHub explícitamente:

uvx --from "git+https://github.com/chigwell/telegram-mcp.git@<pinned-release-tag-or-commit>" telegram-mcp-generate-session

Transportes

El servidor habla tres transportes MCP, seleccionados con MCP_TRANSPORT:

Valor	Transporte	Caso de uso
`stdio`	stdio (predeterminado)	Un proceso de servidor dedicado por cliente MCP
`http`	HTTP transmitible	Un servidor compartido para muchos clientes (Claude Code, Codex, Cursor)
`sse`	SSE (HTTP heredado)	Clientes que solo admiten el transporte SSE obsoleto

Para http y sse, el servidor se vincula a MCP_HOST:MCP_PORT (predeterminado 127.0.0.1:8765); el endpoint de HTTP transmitible es /mcp, el endpoint de SSE es /sse.

Si el servidor es alcanzable a través de un dominio (por ejemplo, detrás de un proxy inverso) en lugar de solo 127.0.0.1/localhost, establece MCP_ALLOWED_HOSTS (y opcionalmente MCP_ALLOWED_ORIGINS) para habilitar la protección contra reenlace de DNS y permitir ese encabezado Host, por ejemplo, MCP_ALLOWED_HOSTS=mcp.example.com. Separados por comas; admite un sufijo :* para permitir cualquier puerto. Sin configurar, la protección contra reenlace de DNS permanece desactivada (el valor predeterminado histórico).

Prefiere http cuando más de un cliente MCP (o muchas sesiones de agentes de codificación) usarán el servidor: un solo proceso de larga duración mantiene una conexión de Telegram, en lugar de que cada cliente genere su propia sesión de Telethon — Telegram limita y puede marcar cuentas que abren muchas sesiones paralelas.

Registra el servidor compartido con los clientes:

# Claude Code
claude mcp add --transport http telegram http://127.0.0.1:8765/mcp

# Codex
codex mcp add telegram --url http://127.0.0.1:8765/mcp

Para clientes solo stdio, puentea con mcp-remote:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp"]
    }
  }
}

Configuración de múltiples cuentas

Usa variables de sesión con sufijo para configurar múltiples cuentas de Telegram:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING_WORK=session_string_for_work
TELEGRAM_SESSION_STRING_PERSONAL=session_string_for_personal

Las etiquetas se convierten a minúsculas y se convierten en el valor del parámetro account en las herramientas.

En modo de una sola cuenta, account es opcional.
En modo de múltiples cuentas, las herramientas de escritura requieren account.
Las herramientas de solo lectura se distribuyen a todas las cuentas cuando se omite account.

Ejemplos de indicaciones:

"Lista mis cuentas"
"Muestra mensajes no leídos de todas las cuentas"

Pool de sesiones (una cuenta, varios clientes concurrentes)

Para ejecutar varios clientes MCP contra la misma cuenta de Telegram a la vez (por ejemplo, la aplicación de escritorio y un CLI de terminal), dale a cada cliente su propia sesión autorizada. Telegram prohíbe que una sesión (clave de autenticación) se use desde dos IPs simultáneamente, por lo que en un host con VPN o doble pila, dos clientes locales pueden colisionar con AuthKeyDuplicatedError. Enumera varias cadenas de sesión intercambiables en TELEGRAM_SESSION_STRINGS (separadas por espacios, comas o punto y coma); cada proceso reclama una libre mediante un bloqueo de archivo de asesoramiento, de modo que los clientes eligen de manera determinista sesiones distintas:

TELEGRAM_SESSION_STRINGS=<session A> <session B> <session C>

Genera sesiones adicionales con uv run session_string_generator.py. El grupo tiene prioridad sobre TELEGRAM_SESSION_STRING para la cuenta predeterminada. Como red de seguridad adicional, un AuthKeyDuplicatedError transitorio en el momento de la conexión (por ejemplo, durante una reconexión de VPN) se reintenta con retroceso antes de que el servidor se rinda.

Ajusta el grupo al número de clientes que realmente ejecutas de forma concurrente. Si cada espacio ya está reclamado, el servidor se niega a iniciarse con un error explícito en lugar de reutilizar una sesión que otro cliente posee: la reutilización haría que Telegram invalide permanentemente esa sesión para ambos clientes.

"Send this from my work account to @example"

Identidad del dispositivo

Estas variables opcionales controlan cómo aparece el cliente en Telegram en Configuración > Dispositivos (la lista de sesiones activas):

TELEGRAM_DEVICE_MODEL=Telegram MCP
TELEGRAM_SYSTEM_VERSION=1.0
TELEGRAM_APP_VERSION=1.0

Si no se establecen, Telethon recurre a la plataforma del host (por ejemplo, arm64). Debido a que estos valores se reenvían en cada conexión, un servidor de larga duración sobrescribiría el nombre elegido durante el inicio de sesión en cada reconexión, así que configúralos para mantener un nombre de dispositivo estable y reconocible. Las mismas variables son leídas tanto por el generador de cadenas de sesión (al iniciar sesión) como por el servidor (en cada conexión), así que configúralas en el mismo lugar que tus otras credenciales.

Soporte de proxy

Enruta el tráfico de Telegram a través de un proxy configurando las variables de entorno TELEGRAM_PROXY_*. Los tipos admitidos son socks5, socks4, http y mtproxy.

Los proxies SOCKS y HTTP requieren el paquete opcional python-socks:

uv sync --extra proxy
# or
pip install python-socks

Configuración de cuenta única:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USERNAME=optional_user
TELEGRAM_PROXY_PASSWORD=optional_pass
TELEGRAM_PROXY_RDNS=true

MTProxy:

TELEGRAM_PROXY_TYPE=mtproxy
TELEGRAM_PROXY_HOST=mtproxy.example
TELEGRAM_PROXY_PORT=443
TELEGRAM_PROXY_SECRET=ee0123456789abcdef...

Las anulaciones por cuenta usan el mismo sufijo _<LABEL> que las variables de sesión y tienen prioridad sobre los valores predeterminados sin sufijo:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080

TELEGRAM_PROXY_TYPE_WORK=http
TELEGRAM_PROXY_HOST_WORK=proxy.work.example
TELEGRAM_PROXY_PORT_WORK=3128

Los ajustes de proxy mal configurados (tipo desconocido, falta de host/puerto, puerto inválido, secreto MTProxy faltante o un paquete python-socks faltante) hacen que el servidor falle rápidamente al inicio con un mensaje de error claro en lugar de omitir silenciosamente el proxy.

Seguridad de rutas de archivo

Las herramientas de rutas de archivo están deshabilitadas hasta que se configuren raíces permitidas. Esto afecta a herramientas como send_file, download_media, upload_file, send_voice, send_sticker, set_profile_photo y edit_chat_photo.

Las raíces permitidas pueden provenir de:

Argumentos de CLI del servidor, utilizados como respaldo.
Raíces del cliente MCP, cuando el cliente las admite.

Comportamiento de seguridad:

Las raíces MCP del cliente reemplazan las raíces CLI del servidor cuando están disponibles.
Algunos clientes (notablemente Cursor) devuelven raíces de espacio de trabajo como rutas absolutas simples en lugar de URIs file://. Eso rompe la validación del SDK MCP de list_roots; el servidor recupera esas rutas absolutas del error de validación para que las herramientas de rutas de archivo sigan funcionando.
Las raíces de cliente vacías se tratan como denegar todo de forma predeterminada. Algunos clientes implementan la capacidad de Roots pero anuncian una lista vacía, lo que deshabilita las herramientas de archivo incluso cuando se configuran raíces CLI del servidor. Establece TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=1 para recurrir a las raíces CLI del servidor en ese caso (opt-in; el valor predeterminado sigue siendo denegar todo). El mismo opt-in también se aplica cuando list_roots falla inesperadamente y no se pudieron recuperar rutas de cliente.
Las rutas se resuelven a través de rutas reales y deben permanecer dentro de una raíz permitida.
Se rechazan los patrones de ruta de traversal, similares a comodines, similares a shell y de byte nulo.
Las rutas relativas se resuelven bajo la primera raíz permitida.
Las descargas se predeterminan a <first_root>/downloads/.
Se aplican límites de tamaño y extensión para herramientas de medios sensibles.

Ejecutar con raíces permitidas:

uv run main.py /data/telegram /tmp/telegram-mcp

Desde una configuración de cliente MCP, pasa las mismas raíces después de main.py:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py",
        "/data/telegram",
        "/tmp/telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Docker

Construye la imagen:

docker build -t telegram-mcp:latest .

Servidor compartido (recomendado)

Ejecuta un contenedor de larga duración que sirva HTTP transmisible y apunta cada cliente MCP a él (consulta Transportes para el registro de clientes):

docker run -d --name telegram-mcp --restart unless-stopped \
  --env-file .env \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -p 127.0.0.1:8765:8765 \
  telegram-mcp:latest

MCP_HOST=0.0.0.0 se enlaza dentro del contenedor para que el puerto publicado funcione; -p 127.0.0.1:8765:8765 mantiene el servidor accesible solo desde la máquina local: el endpoint no está autenticado, así que nunca lo publiques en una interfaz pública.

El archivo Compose incluido ejecuta la misma configuración:

docker compose up --build -d

Un contenedor por cliente (stdio)

Alternativamente, un cliente MCP puede generar un contenedor dedicado por sí mismo:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/full/path/to/.env", "telegram-mcp:latest"]
    }
  }
}

Esto está bien para un solo cliente, pero con varios clientes (o agentes de codificación que generan sesiones de subagentes) cada uno inicia su propio contenedor y su propia sesión de Telegram, lo que Telegram limita; un cliente que sale de forma no limpia también puede dejar su contenedor en ejecución. Prefiere el servidor compartido anterior en esas configuraciones.

Para múltiples cuentas, pasa variables como TELEGRAM_SESSION_STRING_WORK y TELEGRAM_SESSION_STRING_PERSONAL.

Desarrollo

La implementación se divide en un pequeño punto de entrada de compatibilidad y código de paquete modular:

main.py                    # historical entrypoint and compatibility exports
telegram_mcp/runtime.py    # shared MCP setup, account routing, validation, file safety
telegram_mcp/runner.py     # application startup
telegram_mcp/tools/        # tool modules grouped by domain
sanitize.py                # output sanitization helpers
tests/                     # pytest suite

Ejecuta pruebas:

uv run pytest

Ejecuta pruebas con cobertura:

uv run pytest --cov --cov-report=term-missing --cov-report=xml

La cobertura se configura en pyproject.toml con un umbral mínimo del 80% para módulos centrales deterministas y probables por unidad. GitHub Actions ejecuta el mismo comando de cobertura y sube coverage.xml.

Ejecuta comprobaciones de formato:

uv run black --check .
uv run flake8 .

Notas de seguridad

Nunca confirmes .env, cadenas de sesión o archivos .session.
Una cadena de sesión de Telegram otorga acceso a la cuenta a la que pertenece.
El nombre del paquete telegram-mcp en PyPI no está controlado por este proyecto. Evita comandos de instalación basados en PyPI telegram-mcp a menos que la propiedad cambie y el paquete esté verificado.
Este repositorio incluye una protección de inicio de mejor esfuerzo que rechaza distribuciones instaladas de telegram-mcp sin un checkout de fuente o un registro de instalación directa de git/archivo. Esa protección no puede ejecutarse cuando se lanza el paquete PyPI no relacionado en sí, así que usa instalaciones basadas en clon o git explícito.
Prefiere cadenas de sesión sobre sesiones de archivo al ejecutar múltiples instancias de servidor.
Por defecto, las llamadas a la API de Telegram van directamente desde tu máquina/contenedor a Telegram. Si TELEGRAM_PROXY_* está configurado, el tráfico de Telegram se enruta a través del proxy SOCKS/HTTP/MTProxy configurado en su lugar.
El contenido de Telegram generado por el usuario se sanitiza antes de devolverse a los clientes MCP.

Protección contra inyección de prompts

Los mensajes de Telegram, nombres de visualización, títulos de chat y etiquetas de botones son contenido no confiable. El servidor mitiga el riesgo de inyección de prompts con:

Salida JSON estructurada para datos controlados por el usuario cuando sea práctico.
sanitize_user_content(), sanitize_name() y sanitize_dict() para eliminar caracteres de control, eliminar caracteres invisibles y límites de longitud.
Anotaciones de contenido MCP que marcan el contenido devuelto como datos de audiencia de usuario.
Descripciones de herramientas que advierten a los clientes que no traten los campos de Telegram devueltos como instrucciones de modelo.
Sin filtrado frágil basado en palabras clave.

Solución de problemas

No hay sesión de Telegram configurada: establece TELEGRAM_SESSION_STRING, TELEGRAM_SESSION_NAME o variantes de múltiples cuentas con sufijo.
La sesión no está autorizada: ejecuta uv run session_string_generator.py --qr fuera del servidor MCP cuando puedas escanear desde una aplicación de Telegram existente, o uv run session_string_generator.py --phone cuando necesites inicio de sesión con código telefónico. Luego establece TELEGRAM_SESSION_STRING en .env. El servidor MCP no realiza inicio de sesión interactivo con código telefónico a través de stdio.
Credenciales de API inválidas: verifica TELEGRAM_API_ID y TELEGRAM_API_HASH en my.telegram.org/apps.
La base de datos está bloqueada: prefiere sesiones de cadena, o asegúrate de que ningún otro proceso esté usando la misma sesión de archivo.
Las herramientas de archivo están deshabilitadas: pasa raíces permitidas o configura raíces MCP en tu cliente.
Ruta rechazada: asegúrate de que la ruta esté dentro de una raíz permitida y no use patrones de traversal o comodines.
Errores de autenticación después de cambios de contraseña: regenera tu cadena de sesión.
Herramienta solo para bots rechazada: las cuentas de usuario normales no pueden administrar la configuración de comandos de bots.
¿Necesitas detalles?: revisa los registros de tu cliente MCP, la salida del terminal y mcp_errors.log.

Contribuciones

Haz un fork y clona el repositorio.
Instala dependencias y ganchos de git:
- uv sync
- uv run pre-commit install --hook-type pre-commit --hook-type pre-push
Crea una rama enfocada.
Agrega o actualiza pruebas cuando cambie el comportamiento.
Ejecuta comprobaciones localmente:
- uv run pre-commit run --all-files
- uv run pre-commit run --hook-stage pre-push --all-files
Abre una solicitud de extracción con una descripción concisa.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0.

Agradecimientos

Mantenido por @chigwell y @l1v0n1. Se aceptan PRs.