Telegram MCP Server

Conéctate a tu cuenta de Telegram para leer y enviar mensajes.

GitHub
7
Prueba este MCPPatrocinado

Documentación

Telegram MCP Server

Conecta Claude a tu cuenta de Telegram para leer y enviar mensajes.

Características

La mayoría de chats, usuarios y grupos pueden referenciarse por id numérico, @username, número de teléfono, enlace t.me o el literal "me" — el servidor los resuelve por ti (y calienta la caché de entidades de Telethon automáticamente para que los ids crudos también funcionen).

Herramientas Disponibles

Lectura

  • get_me – Información sobre la cuenta autenticada
  • get_chats – Lista paginada de chats (nombres, ids, contadores de no leídos, estado de fijado); admite chats archivados
  • get_messages – Historial de mensajes paginado para un chat (lo marca como leído); incluye información de medios y reacciones
  • search_messages – Buscar por texto, globalmente o dentro de un solo chat
  • get_pinned_messages – Listar mensajes fijados en un chat
  • get_entity_info – Buscar un usuario/grupo/canal por id, nombre de usuario, teléfono o enlace
  • get_participants – Listar miembros de un grupo o canal

Envío y edición

  • send_message – Enviar texto (Markdown), opcionalmente como respuesta
  • edit_message – Editar un mensaje que enviaste
  • delete_messages – Eliminar mensajes (para todos o solo para ti)
  • forward_messages – Reenviar mensajes entre chats
  • send_reaction – Añadir o quitar una reacción emoji
  • pin_message / unpin_message – Fijar o desfijar mensajes
  • mark_messages_read – Marcar los mensajes no leídos de un chat como leídos

Medios

  • send_file – Enviar una foto, video, documento o nota de voz desde el disco
  • download_media – Descargar los medios adjuntos de un mensaje al disco

Contactos y usuarios

  • get_contacts – Listar contactos guardados
  • add_contact / delete_contact – Gestionar contactos
  • block_user / unblock_user – Gestión de bloqueos

Gestión de chats y canales

  • create_group – Crear un grupo básico
  • create_channel – Crear un canal o supergrupo
  • join_chat / leave_chat – Unirse (por nombre de usuario o enlace de invitación) o salir
  • archive_chat – Archivar / desarchivar un chat
  • mute_chat – Silenciar / activar notificaciones

Redacción con conciencia de estilo

  • get_conversation_context – Mensajes recientes + tu guía convostyle.txt para que Claude pueda igualar tu estilo de escritura

Guía de Configuración

Paso 1: Obtén tus Credenciales de la API de Telegram

  1. Ve a https://my.telegram.org/apps
  2. Inicia sesión y crea una aplicación
  3. Guarda tu API ID y API Hash

Paso 2: Instalación

# Clone the repository
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

# Set up Python environment
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Paso 3: Configuración

# Copy the example file
cp .env.example .env

# Edit .env and add your API credentials:
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here

Paso 4: Autenticación

Desde la raíz del repositorio:

uv run telegram-auth

Sigue las indicaciones:

  • Ingresa tu número de teléfono (con código de país, p. ej., +1234567890)
  • Ingresa el código enviado a tu Telegram
  • Ingresa tu contraseña 2FA si tienes una

Esto escribe TELEGRAM_SESSION_STRING en tu .env.

Paso 5: Añadir a Claude Desktop

Encuentra tu archivo de configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade esta configuración (reemplaza la ruta con la ubicación de tu clon):

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-telegram", "run", "telegram-mcp"]
    }
  }
}

Si uv no está en el PATH de Claude Desktop, usa su ruta absoluta (which uv). Alternativamente, apunta command al Python de tu venv y usa ["-m", "mcp_telegram"] como argumentos, con cwd configurado en la raíz del repositorio.

Reinicia Claude Desktop.

Uso

Después de la configuración, puedes pedirle a Claude que:

  • "Revisa mis mensajes de Telegram"
  • "Envía un mensaje a [nombre del contacto]"
  • "¿Cuáles son mis chats no leídos?"
  • "Responde al último mensaje de [nombre del contacto]"

Guía de Estilo (Opcional)

Crea src/mcp_telegram/convostyle.txt para ayudar a Claude a igualar tu estilo de escritura:

I text casually with friends, formally with work contacts.
I use emojis sparingly and prefer short messages.

Solución de Problemas

Problemas de Autenticación

Si la autenticación falla:

  1. Verifica tus credenciales de API en .env
  2. Elimina la línea TELEGRAM_SESSION_STRING de .env
  3. Ejecuta uv run telegram-auth de nuevo

Errores Comunes

  • "Por favor, establece TELEGRAM_API_ID y TELEGRAM_API_HASH": Falta el archivo .env o las credenciales
  • "La cadena de sesión no es válida o ha expirado": Vuelve a ejecutar la autenticación
  • La contraseña 2FA no se muestra: Esto es normal - sigue escribiendo

Requisitos

  • Python 3.10+
  • Claude Desktop
  • Cuenta de Telegram

Licencia

Apache 2.0