telegram-mcp

Un servidor del Protocolo de Contexto de Modelos (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 e inspeccionar IDs de estado de emoji para cuentas y canales

Related MCP server: io.github.daedalus/mcp-telegram-bot

Configuración

Instalación

Opción 1: Descargar el binario precompilado

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

• 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 en 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 introduzcas tu número de teléfono

   • Te enviará un código de verificación a través de Telegram

   • Te pedirá 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 que aparece en la salida. Se verá algo así:

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

Uso

Como servidor MCP

Añádelo a tu 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 asegura que el servidor MCP utilice 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 al que 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áx: 100)

  • offsetId: ID de mensaje para la paginación

• messages_search - Buscar mensajes

  • query (obligatorio): Consulta de búsqueda

  • chatId: Chat específico en el que 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áx: 300)

Herramientas de estado

• status_getCurrent - Obtener el estado de emoji actual de un contacto

  • peerId: Contacto objetivo, predeterminado a self

• status_setEmoji - Establecer o borrar un estado de emoji

  • peerId: Contacto objetivo, predeterminado a self

  • emojiId: ID de documento de emoji personalizado, obligatorio a menos que clear=true

  • isCollectible: Establecer en true cuando emojiId sea 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 de emoji predeterminados disponibles

  • scope: self o channel (predeterminado: self)

  • limit: Máximo de IDs a devolver (predeterminado: 100)

• status_listCollectibles - Listar los IDs coleccionables propios utilizables como estados de emoji personales

  • owner: Contacto a inspeccionar, predeterminado a self

  • limit: Máximo de coleccionables a devolver (predeterminado: 100)

Herramientas de diálogo

• 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 la sesión en el directorio bot-data/.