mcp-telegram

Servidor MCP de Telegram que utiliza la API de Usuario (MTProto) con ACL de denegación predeterminada, permisos granulares por chat, envío de archivos, descarga de medios y limitación de velocidad.

GitHub

Prueba este MCPPatrocinado

Documentación

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 tú.

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

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 de 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, mensajes masivos, scraping) puede resultar en la suspensión de tu cuenta. Eres el único responsable del uso que le des a esta herramienta.

Contenido

Características
Qué puedes hacer con ello
Cómo se compara con chaindead/telegram-mcp
Inicio rápido
Configuración del cliente
Referencia de configuración
Seguridad

Características

Herramienta	Qué hace	Permiso requerido
`tg_me`	Devuelve la información de la cuenta actual	—
`tg_dialogs`	Lista los diálogos visibles para la lista blanca ACL	—
`tg_history`	Obtiene el historial de mensajes con paginación, filtrado por fecha y descarga de medios	`read`
`tg_search`	Busca mensajes en un chat por consulta de texto, con filtro opcional de remitente	`read`
`tg_send`	Envía un mensaje de texto o archivo, con respuesta opcional	`send`
`tg_forward`	Reenvía mensajes de un chat a otro	`read` + `send`
`tg_draft`	Guarda un borrador de mensaje (no lo envía)	`draft`
`tg_mark_read`	Marca un chat como leído	`mark_read`

Capacidades adicionales:

Envío de archivos y fotos
Reenvío de mensajes entre chats
Respuesta 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 diferida de pares — evita errores de FLOOD_WAIT al iniciar
Limitación de velocidad global a nivel de RPC

Qué puedes hacer con ello

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

Ponerte al día con los mensajes

"Revisa mis mensajes de Telegram no leídos y dame un resumen"
"¿Qué escribió @alice en las últimas 24 horas?"
"Muéstrame los mensajes del chat Dev Team desde el lunes"

Responder y comunicarte

"Redacta una respuesta al último mensaje de @bob — no la envíes todavía"
"Envía 'suena bien, nos vemos a las 3pm' a @alice"
"Responde al mensaje 1234 en el chat del proyecto con mis comentarios"

Gestiona tu bandeja de entrada

"Marca 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"

Investiga y analiza

"Encuentra 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?"

Cómo se compara con chaindead/telegram-mcp

	mcp-telegram	chaindead/telegram-mcp
Control de acceso	Lista blanca ACL de denegación por defecto con permisos granulares por chat	Acceso completo a todos los chats
Direccionamiento de pares	Referencias tipadas (`user:ID`, `chat:ID`, `channel:ID`)	Solo IDs numéricos (propenso a colisiones)
Configuración	Configuración YAML con expansión de variables de entorno	Banderas de línea de comandos
Seguridad al iniciar	Resolución diferida de pares (sin llamadas API masivas)	Resolución inmediata (riesgo de FLOOD_WAIT)
Limitación de velocidad	Middleware integrado de token bucket	Ninguna
Soporte de archivos	Enviar archivos, fotos; descargar medios del historial	Solo texto
Soporte de respuestas	Sí	No
Filtrado por fecha	Sí	No

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

NPX (sin necesidad de instalación):

npx @prgebish/mcp-telegram serve --config config.yaml

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 produce 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 pedirá 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 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 en sintaxis ${...} se expanden al momento de la carga.

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 (Settings > MCP Servers > Add):

{
  "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 por defecto. Solo los chats listados explícitamente en acl.chats son accesibles, y solo con los permisos que especifiques.

Patrones de coincidencia admitidos:

Patrón	Ejemplo	Descripción
`@username`	`@johndoe`	Coincide por nombre de usuario de Telegram (sin distinguir mayúsculas)
`+phone`	`+79001234567`	Coincide por número de teléfono
`user:ID`	`user:123456789`	Coincide con un usuario por ID numérico
`chat:ID`	`chat:987654321`	Coincide con un chat grupal por ID numérico
`channel:ID`	`channel:2225853048`	Coincide con un canal o supergrupo por ID numérico

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

Si el mismo par coincide con múltiples reglas (por ejemplo, mediante @username y user:ID), los permisos se fusionan — nunca se anulan entre sí.

Limitación de velocidad

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

requests_per_second — velocidad sostenida (por defecto: 2.0)
burst — tamaño máximo de ráfaga (por defecto: 3)

Descarga de medios

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

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

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

Seguridad

ACL de denegación por defecto — 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 — aplicados a 0600 (solo lectura/escritura del 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 velocidad — previene el abuso accidental de la API
Zona horaria local — los filtros de fecha usan la zona horaria de tu sistema, no UTC

Licencia

MIT

Si encuentras útil este proyecto, por favor dale una estrella — ayuda a que otros lo descubran.