Telegram MCP

telegram-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con Telegram usando mtcute.

Características

• Enviar mensajes de texto a chats
• Esperar mensajes entrantes en chats específicos
• Leer mensajes de chats
• Buscar mensajes
• Listar y obtener información sobre diálogos (chats)
• Obtener mensajes recientes de todos los chats
• Establecer y consultar IDs de estado emoji para cuentas y canales

Configuración

Instalación

Opción 1: Descargar el binario precompilado

Descarga la última versión para tu plataforma desde la página de versiones:

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz
• macOS (Intel): telegram-mcp-darwin-x64.tar.gz
• Linux: telegram-mcp-linux-x64.tar.gz
• Windows: telegram-mcp-win-x64.exe.zip

Extrae el archivo y haz que el binario sea ejecutable (sistemas Unix):

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

Opción 2: Compilar desde el código fuente

1. Clona el repositorio e instala las dependencias:

   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install
   

2. Compila el ejecutable:

   bun run build
   

Configuración inicial (solo la primera vez)

1. Obtén tus credenciales de la API de Telegram desde https://my.telegram.org

2. Ejecuta la configuración inicial para autenticarte con Telegram:

   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp
   

   El servidor:

   • Te pedirá que ingreses tu número de teléfono
   • Te enviará un código de verificación a través de Telegram
   • Solicitará el código de verificación
   • Mostrará la ruta de almacenamiento absoluta (la necesitarás para la configuración de MCP)

3. Anota la ruta de almacenamiento mostrada en la salida. Se verá algo así:

   Storage path: /Users/username/telegram-mcp/bot-data/session
   

Uso

Como servidor MCP

Agrégalo a la configuración de Claude Desktop usando la ruta de almacenamiento de la configuración inicial:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

Importante: TELEGRAM_STORAGE_PATH debe ser la ruta absoluta mostrada durante la configuración inicial. Esto garantiza que el servidor MCP use la sesión autenticada.

Herramientas disponibles

Herramientas de mensajes

• messages_sendText - Enviar un mensaje de texto a un chat

  • chatId (obligatorio): ID de chat/usuario o nombre de usuario
  • text (obligatorio): Texto del mensaje a enviar
  • replyToMessageId: ID de mensaje opcional para responder

• messages_getHistory - Obtener el historial de mensajes de un chat

  • chatId (obligatorio): ID de chat/usuario o nombre de usuario
  • limit: Número de mensajes (predeterminado: 100, máximo: 100)
  • offsetId: ID de mensaje para paginación

• messages_search - Buscar mensajes

  • query (obligatorio): Consulta de búsqueda
  • chatId: Chat específico para buscar (opcional)
  • limit: Número de resultados (predeterminado: 50)

• messages_getRecent - Obtener mensajes recientes de todos los chats

  • limit: Número de chats (predeterminado: 10)
  • messagesPerChat: Mensajes por chat (predeterminado: 10)

Herramientas interactivas

• wait_for_reply - Esperar el siguiente mensaje en un chat
  • chatId (obligatorio): ID de chat/usuario o nombre de usuario del que esperar un mensaje
  • timeoutSeconds: Tiempo de espera en segundos (predeterminado: 60, máximo: 300)

Herramientas de estado

• status_getCurrent - Obtener el estado emoji actual de un peer

  • peerId: Peer de destino, por defecto self

• status_setEmoji - Establecer o borrar un estado emoji

  • peerId: Peer de destino, por defecto self
  • emojiId: ID de documento de emoji personalizado, obligatorio a menos que clear=true
  • isCollectible: Establecer true cuando emojiId es un ID coleccionable
  • until: Marca de tiempo ISO-8601 opcional o cadena de marca de tiempo Unix
  • clear: Borrar el estado actual en lugar de establecer uno

• status_listAvailable - Listar los IDs de estado emoji predeterminados disponibles

  • scope: self o channel (predeterminado: self)
  • limit: Máximo de IDs a devolver (predeterminado: 100)

• status_listCollectibles - Listar los IDs coleccionables propiedad del usuario utilizables como estados emoji propios

  • owner: Peer a inspeccionar, por defecto self
  • limit: Máximo de coleccionables a devolver (predeterminado: 100)

Herramientas de diálogos

• dialogs_list - Listar todos los diálogos

  • limit: Máximo de diálogos (predeterminado: 50)
  • filter: Opciones de filtro (onlyUsers, onlyGroups, onlyChannels)

• dialogs_getInfo - Obtener información detallada del diálogo

  • chatId (obligatorio): ID de chat/usuario o nombre de usuario

Desarrollo

Ejecutar en modo de desarrollo:

bun run dev

El servidor almacena los datos de sesión en el directorio bot-data/.