MCP Telegram

Servidor MCP de Telegram con 20 herramientas: leer chats, buscar mensajes, descargar medios a través de MTProto

Documentación

Servidor MCP de Telegram

📖 Documentación · ☁️ Versión en la nube — conecta Telegram a Claude.ai o ChatGPT en 30 segundos con código QR, sin necesidad de claves API.

Servidor MCP de Telegram — un servidor del Protocolo de Contexto de Modelos (MCP) que conecta asistentes de IA como Claude y ChatGPT a Telegram mediante el protocolo MTProto. A diferencia de los bots, este funciona como un userbot — opera bajo tu cuenta personal de Telegram usando GramJS, lo que te da acceso completo a tus chats, contactos e historial de mensajes.

Características

Cobertura integral de herramientas — el servidor MCP de Telegram más completo disponible
Protocolo MTProto — acceso directo a la API de Telegram, no la API de Bot limitada
Userbot — opera como tu cuenta personal, no como un bot
Completo — mensajería, reacciones, encuestas, mensajes programados, stickers, medios, contactos y más
Temas de foros — lista de temas, lectura de mensajes por tema, envío a temas específicos, recuento de no leídos por tema
Stickers — búsqueda de paquetes de stickers, navegación de stickers instalados/recientes, envío de stickers a cualquier chat
Gestión de cuenta y perfil — actualizar perfil, establecer estado de emoji, cumpleaños, canal personal, foto de perfil, gestionar ajustes de privacidad, sesiones, temporizadores de auto-eliminación
Carpetas de chats — crear, editar, eliminar y reordenar carpetas, alternar etiquetas de carpeta, leer carpetas sugeridas (v1.33.0)
Privacidad global — leer y establecer ajustes de privacidad de toda la cuenta (v1.33.0)
Búsqueda global — buscar mensajes en todos los chats a la vez
Sondeo en tiempo real — obtener actualizaciones mediante cursores sin estado; el agente posee el estado de {pts, qts, date}
Bots y botones en línea — consultar bots en línea, enviar resultados, presionar botones de devolución de llamada
Historias — leer historias de contactos, obtener estadísticas de vistas de historias; publicar/editar/eliminar historias, reaccionar, fijar, modo sigiloso, archivar, reportar (v1.30.0)
Discusión — obtener información del grupo de discusión para publicaciones de canal con comentarios, listar grupos elegibles para discusión (v1.30.0)
Confirmaciones de lectura — quién leyó un mensaje en un grupo pequeño, cuándo se leyó tu mensaje privado (v1.30.0)
Controles de administrador — alternar firmas de canal, anti-spam, modo foro, prehistoria; aprobar solicitudes de unión
Estadísticas — análisis de canales y supergrupos (GetBroadcastStats / GetMegagroupStats)
Impulsos y Negocios — estado de impulsos, lista de impulsores, CRUD de enlaces de chat de Telegram Business, horario laboral, ubicación, mensajes de saludo/ausencia/introducción
Regalos estrella — explorar regalos disponibles y guardados, guardar/convertir regalos, gestionar saldo y suscripciones de Stars (opt-in mediante MCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
Demonio compartido — un proceso en segundo plano atiende a múltiples clientes MCP sobre una sola sesión de Telegram; consulta la guía de demonio compartido (v1.38.0)
Inicio de sesión con código QR — autenticación escaneando un código QR en la aplicación de Telegram
Persistencia de sesión — inicia sesión una vez, mantente conectado entre reinicios
Salida legible para humanos — los nombres de remitentes se resuelven, no solo IDs numéricos
Funciona con cualquier cliente MCP — Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra, etc.

Requisitos previos

Node.js 18 o posterior
Credenciales de API de Telegram — API_ID y API_HASH de my.telegram.org

Inicio rápido

1. Obtén las credenciales de API de Telegram

Ve a my.telegram.org e inicia sesión con tu número de teléfono.
Navega a Herramientas de desarrollo de API.
Crea una nueva aplicación (cualquier nombre y plataforma).
Copia el App api_id y el App api_hash.

2. Inicio de sesión

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login

Aparecerá un código QR en la terminal. Abre Telegram en tu teléfono, ve a Configuración > Dispositivos > Vincular dispositivo de escritorio y escanea el código. La sesión se guarda en ~/.mcp-telegram/session y se reutiliza automáticamente.

Ruta de sesión personalizada: establece TELEGRAM_SESSION_PATH=/path/to/session para almacenar el archivo de sesión en otro lugar.

Verificación en dos pasos (2FA): si tu cuenta tiene una contraseña de nube habilitada, escanear el código QR no es suficiente — Telegram también requiere la contraseña. Proporciónala mediante TELEGRAM_2FA_PASSWORD para que el inicio de sesión pueda completarse:
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login
La contraseña solo se usa localmente para responder al desafío SRP de Telegram y nunca se persiste.

3. Añadir a Claude

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

¡Eso es todo! Pide a Claude que ejecute telegram-status para verificar.

Múltiples cuentas

Usa TELEGRAM_SESSION_PATH para ejecutar cuentas de Telegram separadas en paralelo:

# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login

Luego añade cada una como un servidor MCP separado:

claude mcp add telegram-work -s user \
  -e TELEGRAM_API_ID=ID1 \
  -e TELEGRAM_API_HASH=HASH1 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
  -- npx @overpod/mcp-telegram

claude mcp add telegram-personal -s user \
  -e TELEGRAM_API_ID=ID2 \
  -e TELEGRAM_API_HASH=HASH2 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
  -- npx @overpod/mcp-telegram

Cada cuenta tiene su propio archivo de sesión — sin conflictos.

Múltiples agentes / clientes concurrentes (demonio compartido)

Lo opuesto a múltiples cuentas: una cuenta manejada por muchos clientes a la vez — varias ventanas de Claude Code, subagentes en paralelo o múltiples IDEs. Normalmente cada proceso abre la misma sesión y se expulsan entre sí con AUTH_KEY_DUPLICATED. El modo de servicio resuelve esto.

Ejecuta un demonio persistente único que posea la única conexión de Telegram. Cada otro proceso detecta automáticamente el demonio (mediante un bloqueo de PID) y se convierte en un cliente ligero que envía llamadas de herramientas a través de un socket Unix local:

# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)

Luego apunta cada cliente MCP a la misma instalación con el mismo TELEGRAM_SESSION_PATH — sin argumento serve. Se conectan al demonio automáticamente; cerrar cualquier cliente nunca interrumpe la conexión compartida. Las credenciales solo las requiere el demonio (el propietario), por lo que los comandos de los clientes pueden omitir TELEGRAM_API_ID/TELEGRAM_API_HASH y mantenerlas donde se ejecuta el demonio.

Consulta la guía de demonio compartido para una unidad de systemd y uso con SSH.

Soporte de proxy

Si Telegram está bloqueado o estás ejecutando en un entorno contenedorizado (Docker, K3s), usa un SOCKS5 o MTProxy:

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram

Variable	Descripción
`TELEGRAM_PROXY_IP`	Dirección del servidor proxy
`TELEGRAM_PROXY_PORT`	Puerto del servidor proxy
`TELEGRAM_PROXY_SOCKS_TYPE`	`4` o `5` (predeterminado: `5`)
`TELEGRAM_PROXY_SECRET`	Secreto de MTProxy (habilita el modo MTProxy)
`TELEGRAM_PROXY_USERNAME`	Autenticación de proxy opcional
`TELEGRAM_PROXY_PASSWORD`	Autenticación de proxy opcional

Conexión mediante WSS (puerto 443)

Si la IP de tu VPS o hosting es accesible en el puerto saliente 443 pero no en el puerto MTProto predeterminado 80 (algunos proveedores de nube bloquean el puerto 80 en los rangos de IP de los DC de Telegram como política antiabuso), establece:

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

Variable	Descripción
`TELEGRAM_USE_WSS`	Cuando `true`, gramJS usa el puerto `443` en lugar del `80` para el transporte TCPFull de MTProto. Predeterminado: `false`. No se puede combinar con `TELEGRAM_PROXY_*` (limitación de gramJS) — si ambos están establecidos, `useWSS` se ignora y el proxy tiene prioridad (se registra una advertencia).

Opciones de instalación

npx (recomendado, cero instalación)

No es necesario clonar ni instalar nada. Solo usa npx @overpod/mcp-telegram.

Instalación global

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

Binario precompilado (sin necesidad de runtime)

Descarga desde Releases — binarios independientes de un solo archivo, cero dependencias:

Plataforma	Servidor	CLI de inicio de sesión
Linux x64	`mcp-telegram-linux-x64`	`mcp-telegram-login-linux-x64`
Linux ARM64	`mcp-telegram-linux-arm64`	`mcp-telegram-login-linux-arm64`
macOS x64	`mcp-telegram-darwin-x64`	`mcp-telegram-login-darwin-x64`
macOS ARM64	`mcp-telegram-darwin-arm64`	`mcp-telegram-login-darwin-arm64`
Windows x64	`mcp-telegram-windows-x64.exe`	`mcp-telegram-login-windows-x64.exe`

# Download (example for Linux x64)
curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login

# Run
./mcp-telegram

Desde el código fuente

git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build

Docker

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

Inicio de sesión (se requiere terminal interactiva):

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

Ejecutar el servidor MCP:

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

Nota: El inicio de sesión debe realizarse una vez mediante terminal. Después, la sesión se persiste en ~/.mcp-telegram y se reutiliza automáticamente.

Uso con clientes MCP

Claude Code (CLI)

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Claude Desktop

Abre tu archivo de configuración:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Añade el servidor de Telegram:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["@overpod/mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Reinicia Claude Desktop.
Pide a Claude: "Ejecuta telegram-login" — aparecerá un código QR. Si la imagen no es visible, también se guarda en ~/.mcp-telegram/qr-login.png. Escanéalo en Telegram (Configuración > Dispositivos > Vincular dispositivo de escritorio).
Pide a Claude: "Ejecuta telegram-status" para verificar la conexión.

Nota: ¡No se requiere terminal! El inicio de sesión funciona completamente a través de Claude Desktop.

Claude Desktop (Binario)

Misma configuración, pero usando el binario precompilado en lugar de npx:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Claude Desktop (Docker)

Inicia sesión primero mediante terminal (consulta la sección Docker anterior).
Añade a tu archivo de configuración:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_API_ID=YOUR_ID",
        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
        "mcp-telegram"
      ]
    }
  }
}

Reinicia Claude Desktop. Pide a Claude: "Ejecuta telegram-status" para verificar.

Cursor / VS Code

Añade la misma configuración JSON anterior a tus ajustes de MCP (Cursor Settings > MCP, o configuración de MCP en VS Code).

Mastra

import { MCPClient } from "@mastra/mcp";

const telegramMcp = new MCPClient({
  id: "telegram-mcp",
  servers: {
    telegram: {
      command: "npx",
      args: ["@overpod/mcp-telegram"],
      env: {
        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
      },
    },
  },
});

Herramientas

Todas las herramientas son auto-descubribles mediante MCP — tu cliente de IA verá la lista completa con parámetros y descripciones cuando esté conectado.

Categoría	Herramientas
Autenticación	`telegram-status`, `telegram-login`, `telegram-logout`
Mensajería	`telegram-send-message` (incl. `quoteText` para citas de respuesta verbatim y mensaje Premium `effect`), `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link`
Programado	`telegram-get-scheduled`, `telegram-delete-scheduled`
Lectura	`telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs`
Borradores	`telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts`
Temas del foro	`telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic`
Encuestas	`telegram-create-poll`
Interacción con encuestas (v1.31.0)	`telegram-vote-poll`, `telegram-get-poll-results`, `telegram-get-poll-voters`, `telegram-close-poll`
Reacciones	`telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions`
Reacciones de pago (v1.31.0)	`telegram-send-paid-reaction` (★ Stars), `telegram-toggle-paid-reaction-privacy`, `telegram-get-paid-reaction-privacy`
Transcripción de audio (v1.31.0)	`telegram-transcribe-audio` (Premium), `telegram-get-transcription`, `telegram-rate-transcription`
Verificación de datos (v1.31.0)	`telegram-get-fact-check`, `telegram-edit-fact-check`, `telegram-delete-fact-check`
Stickers	`telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets`
Multimedia	`telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview`
Envío de multimedia enriquecido	`telegram-send-voice`, `telegram-send-video-note` (video redondo), `telegram-send-location` (estático o en vivo), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 fotos/videos agrupados)
Grupos	`telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log`
Información del chat	`telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders`
Carpetas (v1.33.0)	`telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags`
Privacidad global (v1.33.0)	`telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings`
Enlaces de invitación	`telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link`
Contactos	`telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests`
Moderación	`telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam`
Perfiles (lectura)	`telegram-get-profile`, `telegram-update-profile`
Perfil (escritura, v1.32.0)	`telegram-set-emoji-status` (Premium), `telegram-list-emoji-statuses`, `telegram-clear-recent-emoji-statuses`, `telegram-set-profile-color` (Premium), `telegram-set-birthday`, `telegram-set-personal-channel`, `telegram-set-profile-photo`, `telegram-delete-profile-photo`
Cuenta	`telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete`
Fijado	`telegram-pin-message`, `telegram-unpin-message`
Configuración del chat	`telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread`
Interruptores de administrador	`telegram-toggle-channel-signatures`, `telegram-toggle-anti-spam`, `telegram-toggle-forum-mode`, `telegram-toggle-prehistory-hidden`, `telegram-set-chat-reactions`, `telegram-approve-join-request`
Estadísticas	`telegram-get-broadcast-stats`, `telegram-get-megagroup-stats`
Bots en línea y botones	`telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons`
Sondeo en tiempo real	`telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates`
Historias (lectura)	`telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views`
Historias (escritura, v1.30.0)	`telegram-send-story`, `telegram-edit-story`, `telegram-delete-stories`, `telegram-react-to-story`, `telegram-export-story-link`, `telegram-read-stories`, `telegram-toggle-story-pinned`, `telegram-toggle-story-pinned-to-top`, `telegram-activate-stealth-mode` (Premium), `telegram-get-stories-archive`, `telegram-report-story`
Discusión (v1.30.0)	`telegram-get-discussion-message`, `telegram-get-groups-for-discussion`
Confirmaciones de lectura (v1.30.0)	`telegram-get-message-read-participants`, `telegram-get-outbox-read-date`
Boosts	`telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list`
Negocios (v1.32.0)	`telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro`
Opt-in (controlado por entorno)	`telegram-get-group-call`, `telegram-get-group-call-participants` (requiere `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars y regalos `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (requiere `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requiere `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`)

Consejo: Pregunta a tu asistente de IA "¿Qué herramientas de Telegram están disponibles?" para obtener la lista completa con parámetros y descripciones.

Funciones opcionales

Algunas herramientas están deshabilitadas por defecto y deben activarse mediante variables de entorno:

Variable	Valor	Herramientas habilitadas
`MCP_TELEGRAM_ENABLE_GROUP_CALLS`	`1`	`telegram-get-group-call`, `telegram-get-group-call-participants`
`MCP_TELEGRAM_ENABLE_STARS`	`1`	Saldo y transacciones de Stars, opciones de recarga, suscripciones y Star Gifts (explorar / guardar / convertir)
`MCP_TELEGRAM_ENABLE_QUICK_REPLIES`	`1`	`telegram-get-quick-replies`, `telegram-get-quick-reply-messages`

Agrega estos a tu archivo .env o a la configuración del cliente MCP para habilitarlos.

Desarrollo

npm run dev        # Start with file watching (tsx)
npm start          # Start the MCP server
npm run login      # QR code login in terminal
npm run build      # Compile TypeScript
npm run lint       # Check code with Biome
npm run lint:fix   # Auto-fix lint issues
npm run format     # Format code with Biome

Estructura del proyecto

src/
  index.ts            -- MCP server entry point
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login
  tools/              -- Modular tool definitions
    auth.ts           -- Connection & login
    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
    chats.ts          -- Chat listing, group management, admin toggles, stats
    contacts.ts       -- Contacts, profiles, moderation
    media.ts          -- Files, photos, downloads
    reactions.ts      -- Reactions, set-chat-reactions
    extras.ts         -- Pin, schedule, polls, topics
    stickers.ts       -- Sticker sets, send, search, browse
    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
    boosts.ts         -- Boost status, my boosts, boosters list
    stories.ts        -- Stories: list all, peer, by-id, view stats
    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
    shared.ts         -- Shared utilities

Pila tecnológica

TypeScript -- ES2022, módulos ESM
GramJS (telegram) -- Cliente MTProto de Telegram
@modelcontextprotocol/sdk -- Marco de servidor MCP
Zod -- Validación de esquema en tiempo de ejecución para parámetros de herramientas
Biome -- Linter y formateador
tsx -- Ejecución de TypeScript sin paso de compilación
dotenv -- Gestión de variables de entorno

Solución de problemas

AUTH_KEY_DUPLICATED

Una sesión de Telegram solo puede ser utilizada por un proceso a la vez. Si obtienes AUTH_KEY_DUPLICATED, significa que otro proceso ya está usando el mismo archivo de sesión.

Solución: Crea sesiones separadas para cada entorno:

# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login

# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login

Luego configura TELEGRAM_SESSION_PATH en la configuración MCP de cada entorno en consecuencia.

Seguridad

Las credenciales de API se almacenan en .env (ignorado por git)
La sesión se almacena en ~/.mcp-telegram/session con permisos 0600 (acceso solo para el propietario)
El directorio de sesión se crea con permisos 0700
El número de teléfono no es necesario -- autenticación solo con QR
No se envían datos a servicios de terceros -- toda la comunicación va directamente a los servidores de Telegram a través de MTProto
Los códigos de inicio de sesión QR se generan localmente y nunca salen de tu máquina
Una sesión por proceso -- usar la misma sesión en múltiples procesos simultáneamente causa errores AUTH_KEY_DUPLICATED (ver Solución de problemas)
Esto es un userbot (cuenta personal), no un bot -- respeta los Términos de Servicio de Telegram

Licencia

MIT