mcp-telegram

Un servidor MCP que conecta asistentes de IA como Claude a tu cuenta real de Telegram mediante la API de usuario (MTProto). No es un bot: Claude lee y envía mensajes como si fueras tú.

Construido con gotd/td y el SDK oficial de MCP para Go.

Términos de servicio de la API de Telegram: Este proyecto utiliza la API de usuario de Telegram. Debes obtener tu propio api_id y api_hash en my.telegram.org y cumplir con los Términos de servicio de la API de Telegram. El uso indebido de la API de usuario (spam, mensajería masiva, scraping) puede resultar en la prohibición de tu cuenta. Eres el único responsable de cómo utilizas esta herramienta.

Contenido

• Características

• Qué puedes hacer con esto

• Comparación con chaindead/telegram-mcp

• Inicio rápido

• Configuración del cliente

• Referencia de configuración

• Seguridad

Características

Capacidades adicionales:

• Envío de archivos y fotos

• Reenvío de mensajes entre chats

• Responder a mensajes específicos

• Descarga de fotos y documentos del historial de mensajes

• Filtrado del historial por rango de fechas (since / until)

• Referencias de pares tipadas (user:ID, chat:ID, channel:ID) para evitar colisiones de ID

• Resolución de pares diferida (lazy) — evita errores FLOOD_WAIT al iniciar

• Limitación de tasa global a nivel de RPC

Qué puedes hacer con esto

Una vez conectado, puedes pedirle a tu asistente de IA cosas como:

Ponerse al día con los mensajes

• "Revisa mis mensajes de Telegram no leídos y hazme un resumen"

• "¿Qué escribió @alice en las últimas 24 horas?"

• "Muéstrame los mensajes del chat del equipo de desarrollo desde el lunes"

Responder y comunicarse

• "Redacta una respuesta al último mensaje de @bob, pero no la envíes todavía"

• "Envía 'me parece bien, reunámonos a las 3pm' a @alice"

• "Responde al mensaje 1234 en el chat del proyecto con mis comentarios"

Gestionar tu bandeja de entrada

• "Marcar todo como leído en el canal de noticias"

• "¿Cuáles de mis chats en la lista blanca tienen mensajes no leídos?"

• "Descarga las fotos de los mensajes de hoy en el chat de diseño"

Investigar y analizar

• "Busca todos los mensajes que mencionen el despliegue en la última semana"

• "Resume la discusión en el chat del equipo de ayer"

• "¿Qué archivos se compartieron en el canal del proyecto este mes?"

Comparación con chaindead/telegram-mcp

Inicio rápido

Requisitos previos

• Go 1.26+

• Una cuenta de Telegram

• Credenciales de API de my.telegram.org (api_id y api_hash)

Instalación

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

Binarios precompilados (macOS / Linux / Windows):

Descárgalos desde GitHub Releases.

Instalación con Go:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

Desde el código fuente:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

Esto genera mcp-telegram (o mcp-telegram.exe en Windows) en el directorio actual.

Autenticación

Ejecuta el comando de autenticación una vez para crear un archivo de sesión. Se te solicitará tu número de teléfono, el código de inicio de sesión y (si está habilitado) tu contraseña de 2FA.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

Configuración

Crea un archivo config.yaml:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

Las variables de entorno con sintaxis ${...} se expanden al cargar.

Configuración del cliente

El servidor se comunica a través de stdio: tu cliente MCP inicia y gestiona el proceso.

Claude Code (CLI — añadir mediante comando):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json o claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (Ajustes > Servidores MCP > Añadir):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

Configuración

ACL

La ACL es de denegación predeterminada. Solo los chats listados explícitamente en acl.chats son accesibles, y solo con los permisos que especifiques.

Patrones de coincidencia admitidos:

Tipos de permiso: read, send, draft, mark_read.

Si el mismo par coincide con varias reglas (por ejemplo, mediante @username y user:ID), los permisos se combinan; nunca se solapan entre sí.

Limitación de tasa

La sección limits.rate configura un token bucket global que envuelve todas las llamadas RPC de Telegram:

• requests_per_second — tasa sostenida (predeterminado: 2.0)

• burst — tamaño máximo de ráfaga (predeterminado: 3)

Descarga de archivos multimedia

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

Cuando se configura, tg_history descargará automáticamente los archivos multimedia al directorio especificado. El parámetro download_to puede sobrescribir la ruta, pero solo dentro de media.directory o sus subdirectorios.

allowed_upload_dirs restringe los directorios desde los cuales tg_send puede leer archivos. El envío de archivos está deshabilitado a menos que esto esté configurado.

Seguridad

• ACL de denegación predeterminada — ningún chat es accesible a menos que esté explícitamente en la lista blanca

• Límite del sistema de archivos — tg_send solo puede leer archivos de allowed_upload_dirs; download_to está restringido a subdirectorios de media.directory

• Permisos del archivo de sesión — forzados a 0600 (lectura/escritura solo para el propietario)

• Sin registro de secretos — los hashes de API, tokens de sesión y claves de autenticación nunca se escriben en los registros

• Sin exposición de hashes de acceso — los hashes de acceso internos de Telegram se eliminan de toda la salida de las herramientas

• Limitación de tasa — evita el abuso accidental de la API

• Zona horaria local — los filtros de fecha utilizan la zona horaria de tu sistema, no UTC

Licencia

MIT

Si este proyecto te resulta útil, por favor dale una estrella: ayuda a que otros lo descubran.