Telegrama MCP

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

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

⚙️ 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:

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

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

🔍 Búsqueda y navegación

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

📝 Gestión de Borradores

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

📂 Manejo de medios

Herramienta	Descripción
`media_download`	📸 Descargar fotos, vídeos y documentos desde mensajes

[!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.