Servidor MCP de Telegram

Un servidor MCP que permite a los asistentes de IA (como Claude) interactuar con tu cuenta de Telegram mediante la API de cliente de usuario (no la API de bot). Desarrollado con @mtproto/core y el framework FastMCP .

Características

Herramientas

• listChannels

  • Enumera los canales/chats de Telegram disponibles a los que puede acceder la cuenta, según el caché del servidor.

  • Parámetros:

    • limit (número, opcional): número máximo de canales a devolver (predeterminado: 50).

  • Salida: Una lista de canales/chats con su ID, título, tipo y hash de acceso (si corresponde).

• searchChannels

  • Busca los canales/chats almacenados en caché por palabras clave en sus nombres.

  • Parámetros:

    • keywords (cadena): palabras clave para buscar en los nombres de los canales.

    • limit (número, opcional): número máximo de resultados a devolver (predeterminado: 100).

  • Salida: Una lista de canales/chats coincidentes.

• getChannelMessages

  • Recupera mensajes recientes de un canal/chat específico usando su ID.

  • Parámetros:

    • channelId (número): el ID numérico del canal/chat (obtenido de listChannels o searchChannels ).

    • limit (número, opcional): número máximo de mensajes a devolver (predeterminado: 100).

    • filterPattern (cadena, opcional): una expresión regular compatible con JavaScript para filtrar mensajes por su contenido de texto.

  • Salida: Una lista de mensajes que contiene ID, fecha, texto e ID del remitente.

Prerrequisitos

1. Node.js: Se recomienda la versión 18 o posterior.

2. Cuenta de Telegram:

   • Necesitas una cuenta de Telegram activa.

   • La verificación en dos pasos (2FA) debe estar habilitada en su cuenta (Configuración → Privacidad y seguridad → Verificación en dos pasos).

3. Credenciales de la API de Telegram:

   • Obtenga un api_id y api_hash creando una nueva aplicación en https://core.telegram.org/api/obtaining_api_id .

Instalación

1. Clonar este repositorio:

   git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL cd telegram-mcp-server

2. Instalar dependencias:

   npm install

Configuración

Hay dos configuraciones independientes que deben configurarse:

1. Configuración del servidor MCP:

   Configure el servidor Telegram MCP usando variables de entorno (en un archivo .env o directamente en su entorno):

   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567

   Reemplace los valores de marcador de posición con sus credenciales reales.

2. Configuración del cliente MCP:

   Configure el software cliente (Claude Desktop, Cursor, etc.) para conectarse al servidor MCP modificando sus archivos de configuración:

   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }

   Para Claude Desktop, el archivo de configuración se encuentra en:

   • En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • En Windows: %APPDATA%/Claude/claude_desktop_config.json

   Importante: reinicie su cliente MCP para aplicar los cambios.

Ejecución del servidor

1. Inicio de sesión inicial (primer paso importante): La primera vez que inicie el servidor (o si su sesión caduca o no es válida), deberá autenticarse con Telegram. Ejecútelo directamente desde su terminal:

   npm start

   • El servidor utilizará las credenciales de su archivo .env .

   • Le solicitará en la terminal que ingrese el código de inicio de sesión enviado a su cuenta de Telegram y su contraseña 2FA si es necesario.

   • Tras iniciar sesión correctamente, se creará un archivo de sesión ( ./data/session.json ). Este archivo permite que el servidor inicie sesión automáticamente en el futuro sin necesidad de códigos ni contraseñas.

   • El servidor también intentará crear o cargar una caché de tus chats ( ./data/dialog_cache.json ). Esto puede tardar un poco la primera vez, especialmente con muchos chats. Los siguientes inicios serán más rápidos si la caché existe.

2. Operación normal: Deberá iniciar el servidor manualmente ejecutando npm start en el directorio del proyecto.

   Una vez que el servidor esté en funcionamiento, su cliente MCP (por ejemplo, Claude Desktop) se conectará a él a través de la URL especificada en su configuración ( http://localhost:8080/sse por defecto).

Solución de problemas

• Solicitudes de inicio de sesión: Si el servidor solicita constantemente códigos de inicio de sesión o contraseñas al iniciarse con el cliente MCP, asegúrese de que el archivo data/session.json exista y sea válido. Es posible que deba ejecutar npm start manualmente una vez para actualizar la sesión. Además, verifique que los permisos del archivo permitan al usuario que ejecuta el cliente MCP leer y escribir en el directorio data .

• Problemas de caché: Si los canales parecen estar desactualizados o faltan, puede eliminar ./data/dialog_cache.json y reiniciar el servidor (ejecute npm start manualmente) para forzar una actualización completa. Esto puede tardar un tiempo.

• No se encuentra el módulo: Asegúrese de ejecutar npm install en el directorio del proyecto. Si el cliente MCP inicia el servidor, verifique que el directorio de trabajo esté configurado correctamente o use rutas absolutas.

• Otros problemas: si encuentra algún otro problema, no dude en abrir un problema en este repositorio del servidor .

Biblioteca de clientes de Telegram

Este repositorio también contiene la biblioteca subyacente telegram-client.js utilizada por el servidor MCP. Para obtener más información sobre el uso directo de la biblioteca (por ejemplo, para scripts personalizados), consulte LIBRARY.md .

Licencia

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