MCP Telegram Server

Un servidor MCP para interactuar con Telegram. Permite buscar, enviar mensajes y gestionar chats utilizando la API de Telegram.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Telegram — Puente de Model Context Protocol (MCP) para Telegram. 8 herramientas eficientes en contexto, multiinquilino, puente MTProto.

Probar la Demo

Abre https://tg-mcp.l1979.ru/setup
Escanea el código QR desde Telegram móvil (Configuración → Dispositivos → Escanear QR) — sin escribir el teléfono, sin OTP, sin 2FA. O ingresa tu número de teléfono como alternativa.
Copia tu token Bearer desde la página de éxito

Luego elige tu camino:

Cliente MCP (asistentes de IA)

Desde la página de configuración, descarga el archivo mcp.json
Agrega el servidor a tu cliente de IA y pregunta: "envía un saludo a mis mensajes guardados en telegram"

API directa (curl)

Ejecuta el comando a continuación (reemplaza TOKEN con el tuyo):

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello!"}}'

Cómo Funciona

Este servidor se sitúa entre tu agente de IA y la API de Telegram:

Your agent → MCP/HTTP → this server → MTProto → Telegram

Qué hace: Te autentica con Telegram (QR o token de teléfono/bot), expone 8 herramientas amigables para IA en lugar de más de 80 micro-APIs, y conecta MTProto crudo para usuarios avanzados. Multiinquilino: un servidor, muchos usuarios, sesiones aisladas.

Características

Característica	Descripción
:building_construction: Transporte Dual	Stdio para clientes MCP locales, HTTP para despliegues remotos (`http-auth` en producción, `http-no-auth` opcional para desarrollo)
:closed_lock_with_key: Autenticación Multi-Usuario	Servidor `http-auth` compartido: un token Bearer por usuario, una cuenta de Telegram por conexión MCP. Inicio de sesión con QR para autenticación instantánea — sin teléfono/OTP/2FA.
:dart: Optimizado para IA	8 herramientas consolidadas frente a más de 80 micro-herramientas: diseño eficiente en contexto, API amigable para LLM, MCP ToolAnnotations
:globe_with_meridians: Puente HTTP-MTProto	Acceso directo con curl a cualquier método de la API de Telegram con resolución de entidades y salvaguardas de seguridad
:shield: ACL de Sesión	Límites opcionales por principal en `http-auth` (`ACL_ENABLED`) — carriles de chat, `read_only`, `blocked_peers`, `allow_mtproto`, `ACL_DENY_UNLISTED_PRINCIPALS`; consulta SECURITY.md
:tv: Configuración QR y Web	Escanea QR desde Telegram móvil para autenticación instantánea (sin teléfono/OTP/2FA) o usa la alternativa de teléfono/código/2FA — disponible en `/setup`
:label: Un Agente, Múltiples Cuentas	`PREFIX_MCP_TOOLS_WITH_ACCOUNT` opcional — cuando un agente usa varias conexiones MCP (mismo servidor, diferentes tokens), prefija los nombres de las herramientas para que no colisionen; no es necesario para alojamiento multi-usuario estándar
:rocket: Soporte de Proxy MTProto	Conéctate mediante proxy MTProto con Fake TLS automático (prefijo EE) y detección estándar de proxy
:card_file_box: Gestión Unificada de Sesiones	Sistema de configuración único para configuración y servidor; archivos de sesión por token en hosts multi-usuario compartidos
:cloud: Almacenamiento de Sesiones S3	Almacena sesiones en almacenamiento de objetos compatible con S3 para despliegues efímeros (Smithery, Fly.io, Railway)
:mag_right: Búsqueda Inteligente	Búsqueda global y por chat de mensajes con soporte de múltiples consultas y deduplicación inteligente
:mag: API de Mensajes Unificada	Herramienta única `get_messages` para búsqueda, navegación, lectura por IDs y respuestas: 5 modos en una
:speech_balloon: Respuestas Universales	Obtén respuestas de publicaciones de canal, temas de foro o cualquier mensaje con un parámetro
:busts_in_silhouette: Descubrimiento Inteligente de Contactos	Busca usuarios, grupos, canales con esquemas de entidad uniformes, detección de foros, enriquecimiento de perfiles
:file_folder: Filtrado por Carpetas	Filtra chats por carpeta de diálogo (archivados, carpetas personalizadas) con ID entero o coincidencia de nombre
:envelope: Mensajería Avanzada	Envía, edita, responde, publica en temas de foro, formato, archivos adjuntos y mensajería por número de teléfono
:paperclip: Manejo Seguro de Archivos	Compartir medios enriquecidos con protección SSRF, límites de tamaño, soporte de álbumes, transmisión opcional de adjuntos HTTP
:outbox_tray: Cargas de Archivos en Línea	Cargas de archivos Data: URI (base64) en el parámetro `files` — funcionan en todos los modos de transporte, nombres de archivo preservados, imágenes enviadas como fotos
:microphone: Transcripción de Voz	Conversión automática de voz a texto para cuentas Premium con procesamiento paralelo y sondeo
:zap: Alto Rendimiento	Operaciones asíncronas, consultas paralelas y procesamiento por lotes consciente de memoria
:shield: Fiabilidad de Producción	Reconexión automática, registro configurable, manejo integral de errores

Inicio Rápido

1. Instalar y autenticar

Ruta más rápida (servidor remoto): Abre /setup → escanea el QR → copia el token (consulta Probar la Demo).

Ruta CLI (stdio local): Ejecuta fast-mcp-telegram-setup una vez para crear una sesión de Telegram — luego fast-mcp-telegram la sirve:

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --phone-number="+123456789"

Alternativa con token de bot (sin teléfono, sin OTP): Configura BOT_API_TOKEN en lugar de --phone-number. Consulta la Guía de Instalación.

2. Configurar el Cliente MCP

Modo stdio (local): Agrega a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json) — stdio (entrada/salida estándar) es el transporte predeterminado para clientes MCP locales:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["fast-mcp-telegram"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash"
      }
    }
  }
}

Modo http-auth (remoto): Agrega a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "url": "https://tg-mcp.l1979.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Obtén tu token escaneando el código QR en la página de configuración o consulta la Guía de Instalación para desplegar tu propio servidor.

3. Comenzar a Usar

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello!"}}

Desplegar en un Servidor Remoto

Despliega tu propio servidor MCP en un VDS — consulta la Guía de Instalación para instrucciones paso a paso.

Herramientas Disponibles

Herramienta	Propósito	Características Clave
`search_messages_globally`	Buscar en todos los chats	Consultas de múltiples términos, filtrado por fecha, filtrado por tipo de chat
`get_messages`	Recuperación unificada de mensajes	Búsqueda/navegación, lectura por IDs, obtención de respuestas (publicaciones/temas/mensajes), filtrado por fecha en todos los modos
`send_message`	Enviar nuevo mensaje	Archivos adjuntos (URLs/locales/data URIs), formato clásico (markdown/html), `parse_mode=rich` Mensajes Enriquecidos, respuesta a temas de foro
`edit_message`	Editar mensaje existente	Formato clásico o `parse_mode=rich`
`find_chats`	Encontrar usuarios/grupos/canales	Búsqueda de múltiples términos, descubrimiento de contactos, filtrado por carpeta, búsqueda por nombre de usuario/teléfono
`get_chat_info`	Obtener información detallada del perfil	Conteo de miembros, biografía/información, estado en línea, temas de foro, grupos comunes, datos enriquecidos
`send_message_to_phone`	Enviar mensajes a números de teléfono	Gestión automática de contactos, limpieza opcional, soporte de archivos (URLs/data URIs), `parse_mode=rich`
`invoke_mtproto`	API directa de Telegram (usuario avanzado)	Métodos MTProto crudos, resolución de entidades, salvaguardas de seguridad — consulta Puente MTProto

Consulta la Referencia de Herramientas para documentación detallada con ejemplos.

Documentación

Guía de Instalación - Configuración local y despliegue de servidor remoto
Referencia de Herramientas - Documentación completa de herramientas
Puente MTProto - Acceso directo a la API mediante curl
Contribuciones - Directrices para colaboradores
Seguridad - Características de seguridad y mejores prácticas

Telemetría

Telemetría anónima de herramientas desde v0.30.1 — latido cada 6 horas, sin credenciales ni contenido de mensajes recopilados. Exclúyete con DO_NOT_TRACK=1. Consulta ADR 0005.

Telemetría del flujo de autenticación desde v0.38.0 — eventos atómicos durante la configuración (teléfono, QR, token de bot, reautorización). Vaciamiento con búfer al completar el flujo. Consulta ADR 0008.

Licencia

Licencia MIT — consulta LICENCIA

mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram