MCP Telegram

Conecta Modelos de Lenguaje Grande a Telegram mediante el Model Context Protocol (MCP).

Construido con Telethon, este servidor permite a los agentes de IA interactuar con Telegram, habilitando funciones como enviar/editar/eliminar mensajes, buscar chats, gestionar borradores, descargar medios y más usando el MTProto.

---

Tabla de Contenidos

• 🚀 Comenzando
  • Requisitos previos
  • Instalación
• ⚙️ Uso
  • Inicio de sesión
  • Conectar al servidor MCP
• 🧰 Herramientas disponibles
  • 📨 Herramientas de mensajería
  • 🔍 Búsqueda y navegación
  • 📝 Gestión de borradores
  • 📂 Manejo de medios
• 🛠️ Solución de problemas
• 🤝 Contribuciones
• 📝 Licencia

---

🚀 Comenzando

Requisitos previos

• Python 3.10 o superior
• uv Instala mediante la guía oficial de uv.

Instalación

Instala la herramienta CLI mcp-telegram:

uv tool install mcp-telegram

⚙️ Uso

[!IMPORTANT] Asegúrate de haber leído y comprendido los Términos de servicio de Telegram antes de usar esta herramienta. El mal uso de esta herramienta puede resultar en restricciones de cuenta.

La herramienta de línea de comandos mcp-telegram es tu punto de entrada.

mcp-telegram --help # See all commands

Inicio de sesión

Primero, autentícate con tu cuenta de Telegram:

mcp-telegram login

Este comando interactivo te pedirá:

• API ID y API Hash: Obtén estos desde my.telegram.org/apps.
• Número de teléfono: Tu número de teléfono registrado en Telegram (formato internacional, p. ej., +1234567890).
• Código de verificación: Enviado a tu cuenta de Telegram al iniciar sesión por primera vez.
• Contraseña 2FA: Si tienes habilitada la autenticación de dos factores.

Tus credenciales se almacenan de forma segura en el archivo de sesión para uso futuro.

[!WARNING] Mantén tus credenciales de API privadas y nunca las compartas públicamente

[!NOTE] Usa mcp-telegram logout para cerrar sesión de la sesión actual o mcp-telegram clear-session para eliminar todos los datos de sesión almacenados.

Conectar al servidor MCP

Para usar MCP Telegram con clientes MCP como Claude Desktop o Cursor, necesitarás configurar el servidor MCP. El proceso de configuración varía según el cliente y el sistema operativo.

Para instrucciones detalladas de configuración, consulta:

• Guía de configuración de MCP para Claude Desktop
• Documentación de MCP para Cursor

El archivo de configuración debe contener:

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

[!Note] Las rutas de configuración varían según el sistema operativo y el cliente. Por ejemplo:

• macOS: ~/Library/Application Support/Claude/ o ~/.cursor/
• Windows: %APPDATA%\Claude\ o %APPDATA%\Cursor\

[!IMPORTANT] Si tu cliente no puede ejecutar mcp-telegram a pesar de que sea accesible en la terminal, intenta usar la ruta completa al ejecutable. Puedes encontrarla ejecutando which mcp-telegram (macOS/Linux) o where mcp-telegram (Windows) en tu terminal. Reemplaza el valor command en la configuración con la ruta completa.

Después de guardar el archivo de configuración, reinicia tu aplicación.

🧰 Herramientas disponibles

Aquí tienes una lista completa de herramientas que puedes usar para interactuar con Telegram a través de MCP:

📨 Herramientas de mensajería

Tool	Descripción
send_message	✉️ Envía mensajes de texto o archivos a cualquier usuario, grupo o canal
edit_message	✏️ Modifica el contenido de mensajes enviados anteriormente
delete_message	🗑️ Elimina uno o varios mensajes
get_messages	📜 Recupera el historial de mensajes con opciones de filtrado avanzadas

🔍 Búsqueda y navegación

Tool	Descripción
search_dialogs	🔎 Encuentra usuarios, grupos y canales por nombre o nombre de usuario
message_from_link	🔗 Accede a mensajes específicos usando enlaces de Telegram

📝 Gestión de borradores

Tool	Descripción
get_draft	📋 Ver el borrador actual de mensaje para cualquier chat
set_draft	✍️ Crear o borrar borradores de mensajes

📂 Manejo de medios

Tool	Descripción
media_download	📸 Descargar fotos, videos y documentos de mensajes

[!Note] Para información detallada de parámetros y casos de uso de ejemplo, ejecuta mcp-telegram tools en tu terminal.

🛠️ Solución de problemas

Errores de base de datos bloqueada

Ejecutar múltiples instancias de mcp-telegram usando el mismo archivo de sesión puede causar errores de database is locked debido al almacenamiento de sesión SQLite de Telethon. Asegúrate de que solo una instancia use un archivo de sesión a la vez.

Detención forzada de procesos existentes

Si necesitas detener procesos potencialmente bloqueados:

• macOS / Linux: pkill -f "mcp-telegram"
• Windows: taskkill /F /IM mcp-telegram.exe /T (Revisa el Administrador de tareas para el nombre exacto del proceso)

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Si deseas ayudar a mejorar MCP Telegram, no dudes en enviar problemas, solicitudes de funciones o pull requests. Tus comentarios y contribuciones ayudan a mejorar este proyecto para todos.

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

---