MCP Telegram

Conecte modelos de lenguaje grandes a Telegram a través del Protocolo de contexto de modelo (MCP) .

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

• 🚀 Primeros pasos

  • Prerrequisitos

  • Instalación

• ⚙️ Uso

  • Acceso

  • Conectarse 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

• 🤝 Contribuyendo

• 📝 Licencia

🚀 Primeros pasos

Prerrequisitos

• Python 3.10 o superior

• Instalar uv a través de la guía oficial de uv .

Instalación

Instalar la herramienta CLI mcp-telegram :

uv tool install mcp-telegram

Related MCP server: crafty-mcp

⚙️ Uso

[!IMPORTANTE] Asegúrate de leer y comprender las Condiciones de Servicio de Telegram antes de usar esta herramienta. El uso indebido de esta herramienta puede resultar en restricciones de cuenta.

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

mcp-telegram --help # See all commands

Acceso

Primero, autentícate con tu cuenta de Telegram:

mcp-telegram login

Este comando interactivo le solicitará lo siguiente:

• ID de API y hash de API: obténgalos en my.telegram.org/apps .

• Número de teléfono: su número de teléfono registrado en Telegram (formato internacional, por ejemplo, +1234567890 ).

• Código de verificación: enviado a su cuenta de Telegram en el primer inicio de sesión.

• Contraseña 2FA: si tiene habilitada la autenticación de dos factores.

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

[!ADVERTENCIA] Mantenga sus credenciales de API privadas y nunca las comparta públicamente

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

Conectarse al servidor MCP

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

Para obtener instrucciones de configuración detalladas, consulte:

• Guía de configuración del MCP de Claude Desktop

• Documentación del cursor MCP

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>"
      }
    }
  }
}

[!Nota] 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\

[!IMPORTANTE] Si su cliente no puede ejecutar mcp-telegram a pesar de estar accesible en la terminal, intente usar la ruta completa del ejecutable. Puede averiguarlo ejecutando which mcp-telegram (macOS/Linux) o where mcp-telegram (Windows) en su terminal. Reemplace el valor command en la configuración con la ruta completa.

Después de guardar el archivo de configuración, reinicie su 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

🔍 Búsqueda y navegación

📝 Gestión de Borradores

📂 Manejo de medios

[!Nota] Para obtener información detallada de los parámetros y casos de uso de ejemplo, ejecute mcp-telegram tools en su terminal.

🛠️ Solución de problemas

Errores de bloqueo de la base de datos

Ejecutar varias instancias mcp-telegram con el mismo archivo de sesión puede provocar errores database is locked debido al almacenamiento de sesiones SQLite de Telethon. Asegúrese de que solo una instancia use un archivo de sesión a la vez.

Si necesita detener procesos potencialmente bloqueados:

• macOS/Linux: pkill -f "mcp-telegram"

• Windows: taskkill /F /IM mcp-telegram.exe /T (Consulte el Administrador de tareas para conocer el nombre exacto del proceso)

🤝 Contribuyendo

¡Agradecemos las contribuciones! Si quieres ayudar a mejorar MCP Telegram, no dudes en enviarnos incidencias, solicitudes de funciones o solicitudes de incorporación de cambios. Tus comentarios y contribuciones ayudan a mejorar este proyecto para todos.

📝 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.