Telegram Archive MCP

Busca mensajes, navega por chats y accede al historial archivado de Telegram desde una instancia autoalojada.

Documentación

Telegram-Archive-MCP

Un pequeño puente que expone cualquier instancia de Telegram-Archive como un servidor MCP, permitiendo a los LLMs buscar mensajes, explorar chats y acceder al historial de Telegram archivado.

Lo que obtienes

Tipo	Para qué se usa	URI MCP / ID de herramienta
Recursos	Explorar estadísticas del archivo, chats y carpetas en modo solo lectura	`telegram-archive://stats` `telegram-archive://chats` `telegram-archive://folders` `telegram-archive://health`
Herramientas	Buscar y recuperar mensajes (paginación por desplazamiento o cursor de claves; días calendario completos en una zona horaria), inspeccionar estadísticas de chats	`search_messages` `get_messages` `get_pinned_messages` `get_messages_by_date` `get_chat_stats` `get_topics` `refresh_stats`

Todo se expone a través de un único endpoint JSON-RPC (/mcp). Los LLMs / Agentes pueden: initialize -> readResource -> listTools -> callTool ... y así sucesivamente.

Inicio rápido (Docker Compose)

services:
  telegram-archive-mcp:
    image: drumsergio/telegram-archive-mcp:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - TELEGRAM_ARCHIVE_URL=http://telegram-archive:3000
      - TELEGRAM_ARCHIVE_USER=your-username
      - TELEGRAM_ARCHIVE_PASS=your-password

Nota de seguridad: El transporte HTTP escucha en 127.0.0.1:8080 por defecto. Si necesitas exponerlo en una red, colócalo detrás de un proxy inverso con autenticación.

Instalación vía npm (transporte stdio)

npx telegram-archive-mcp

O instala globalmente:

npm install -g telegram-archive-mcp
telegram-archive-mcp

Esto descarga el binario Go precompilado desde GitHub Releases para tu plataforma y lo ejecuta con transporte stdio. Requiere al menos una versión publicada.

Compilación local

git clone https://github.com/GeiserX/telegram-archive-mcp
cd telegram-archive-mcp

# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env

go run ./cmd/server

Configuración

Variable	Valor predeterminado	Descripción
`TELEGRAM_ARCHIVE_URL`	`http://localhost:3000`	URL de la instancia de Telegram-Archive (sin / final)
`TELEGRAM_ARCHIVE_USER`	(vacío)	Nombre de usuario de inicio de sesión para autenticación de sesión vía `/api/login`
`TELEGRAM_ARCHIVE_PASS`	(vacío)	Contraseña de inicio de sesión para autenticación de sesión vía `/api/login`
`LISTEN_ADDR`	`127.0.0.1:8080`	Dirección de escucha HTTP (Docker establece `0.0.0.0:8080`)
`MCP_AUTH_TOKEN`	(vacío)	Token Bearer para autenticación HTTP (requerido si no es loopback)
`TRANSPORT`	(vacío = HTTP)	Establecer a `stdio` para transporte stdio

Colócalas en un archivo .env (desde .env.example) o establécelas en el entorno.

Pruebas

Probado con Inspector y actualmente funciona completamente. Antes de hacer un PR, asegúrate de que este servidor MCP se comporte bien a través de este medio.

Ejemplo de configuración para LLMs de clientes

{
  "schema_version": "v1",
  "name_for_human": "Telegram-Archive-MCP",
  "name_for_model": "telegram_archive_mcp",
  "description_for_human": "Search messages, browse chats, and access archived Telegram history.",
  "description_for_model": "Interact with a Telegram-Archive instance that stores archived Telegram messages. First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with telegram-archive://. Use listTools to discover available actions and callTool to execute them.",
  "auth": {
    "type": "bearer",
    "token": "<your MCP_AUTH_TOKEN value>"
  },
  "api": {
    "type": "jsonrpc-mcp",
    "url":  "http://localhost:8080/mcp",
    "init_method": "initialize",
    "session_header": "Mcp-Session-Id"
  },
  "contact_email": "acsdesk@protonmail.com",
  "legal_info_url": "https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE"
}

Créditos

Telegram-Archive -- Archivado y búsqueda de mensajes de Telegram

MCP-GO -- Implementación moderna de MCP

GoReleaser -- Lanzamientos multi-arquitectura sin complicaciones

Mantenedores

@GeiserX.

Contribuciones

¡Siéntete libre de participar! Abre un issue o envía PRs.

Telegram-Archive-MCP sigue el Contributor Covenant Código de Conducta.

Otros Servidores MCP de GeiserX

cashpilot-mcp — Monitoreo de ingresos pasivos
duplicacy-mcp — Monitoreo de salud de respaldos
genieacs-mcp — Gestión de dispositivos TR-069
lynxprompt-mcp — Planos de configuración de IA
pumperly-mcp — Precios de combustible y carga de vehículos eléctricos

Proyectos Relacionados

Proyecto	Descripción
Telegram-Archive	Respaldos automáticos e incrementales de Telegram con un visor web local
telegram-delay-channel-cloner	Bot de Telegram que retransmite mensajes entre canales con retraso configurable
telegram-slskd-local-bot	Descubrimiento y descarga automatizada de música vía bot de Telegram con Soulseek
paperless-telegram-bot	Gestiona documentos de Paperless-NGX completamente a través de Telegram
n8n-nodes-telegram-archive	Nodo comunitario de n8n para Telegram-Archive