mcp-telegram

Servidor MCP para Telegram: permite que los asistentes de IA interactúen con tu cuenta de Telegram

Características

• Gestión de chats: Listar, buscar, silenciar/activar notificaciones de chats

• Mensajes: Leer, buscar, inspeccionar contexto, enviar, redactar, programar, resolver enlaces y realizar copias de seguridad de mensajes

• Resumen con IA: Resume conversaciones de chat utilizando múltiples proveedores de LLM

• Seguro: Sesión almacenada en el Llavero de macOS (almacenamiento basado en archivos en Linux/Windows)

Instalación

go install github.com/tolmachov/mcp-telegram@latest

O compila desde el código fuente:

git clone https://github.com/tolmachov/mcp-telegram.git
cd mcp-telegram
make

Configuración

1. Obtén las credenciales de la API de Telegram

1. Ve a my.telegram.org/apps

2. Crea una aplicación

3. Copia api_id y api_hash

2. Configura el entorno

Almacena las credenciales (Llavero de macOS; JSON en texto plano en ~/.local/state/mcp-telegram/config.json con permisos 0600 en Linux/Windows):

mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234efgh5678

O utiliza un archivo .env:

cp .env.example .env
# Edit .env with your credentials

3. Inicia sesión en Telegram

mcp-telegram login --phone +1234567890

Se te solicitará un código de verificación enviado a tu Telegram.

4. Configura el cliente MCP

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telegram": {
      "command": "mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code

claude mcp add telegram -- /path/to/mcp-telegram run

Establece las variables de entorno en tu archivo .env o pásalas mediante --env.

Herramientas disponibles

19 herramientas expuestas a los clientes MCP. Los mensajes se identifican mediante identificadores de cadena opacos ("42" para mensajes normales, "s:42" para programados); cópialos textualmente de los resultados de las herramientas para llamadas posteriores, nunca los analices ni construyas manualmente.

Recursos disponibles

Los recursos de chats fijados se crean dinámicamente para cada chat fijado y se actualizan en segundo plano; los clientes recibirán resources/list_changed cuando el conjunto cambie.

Prompts disponibles

3 prompts parametrizados que los clientes MCP exponen como comandos de barra diagonal o acciones rápidas.

Ejemplos de prompts

Aquí tienes algunos ejemplos de prompts que puedes usar con asistentes de IA:

Gestión de mensajes

• "Comprueba si hay mensajes importantes sin leer en mi Telegram"

• "Resume todos mis mensajes de Telegram sin leer"

• "Lee y analiza mis mensajes sin leer, prepara borradores de respuesta donde sea necesario"

• "Comprueba los mensajes sin leer no críticos y dame una visión general"

• "Busca mensajes que mencionen 'factura' en mi chat de trabajo de la semana pasada"

• "Abre el contexto alrededor de este enlace de Telegram: https://t.me/example/123"

Organización

• "Analiza mis diálogos de Telegram y sugiere una estructura de carpetas"

• "Ayúdame a categorizar mis chats de Telegram por importancia"

• "Encuentra todas las conversaciones relacionadas con el trabajo y sugiere cómo organizarlas"

Comunicación

• "Monitorea un chat específico para actualizaciones sobre [tema]"

• "Redacta una respuesta educada al último mensaje en [chat]"

• "Comprueba si hay preguntas sin responder en mis chats"

• "Resuelve este enlace de mensaje de Telegram y muéstrame el contexto del hilo"

Copia de seguridad y exportación

• "Haz una copia de seguridad de mi conversación con [contacto] en un archivo"

• "Exporta la última semana de mensajes de [grupo]"

• "Haz una copia de seguridad también de las actualizaciones que solo contienen medios para que no se omita nada"

Resumen de chat

La herramienta SummarizeChat admite múltiples proveedores de LLM:

• sampling (experimental): Utiliza el LLM del cliente MCP mediante MCP Sampling. Solo funciona con clientes que admiten muestreo: VS Code, fast-agent, Continue. NO funciona con Claude Desktop o Claude Code.

• ollama: LLM local mediante Ollama - no requiere clave API

• gemini: API de Google Gemini

• anthropic: API de Anthropic Claude

Configura mediante variables de entorno:

SUMMARIZE_PROVIDER=ollama  # or: sampling, gemini, anthropic
SUMMARIZE_MODEL=           # provider-specific model name

Comandos

# Run MCP server (used by MCP clients)
mcp-telegram run

# Login to Telegram
mcp-telegram login --phone +1234567890

# Logout and delete session
mcp-telegram logout

# Securely store config values (macOS Keychain / file on Linux)
mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete TELEGRAM_API_ID

Claves permitidas: TELEGRAM_API_ID, TELEGRAM_API_HASH, ANTHROPIC_API_KEY, GEMINI_API_KEY.

Opciones de configuración

Acciones destructivas

Herramientas como DeleteMessage solicitan confirmación del usuario mediante elicitación MCP antes de proceder. Si tu cliente MCP no admite la elicitación, el servidor depende de las instrucciones del LLM para confirmar verbalmente antes de ejecutar operaciones destructivas.

Almacenamiento de sesión

• macOS: Almacenado de forma segura en el Llavero.

• Linux/Windows: Almacenado en ~/.local/state/mcp-telegram/session.json con permisos de archivo 0600. El archivo está en texto plano: mantén la cuenta de usuario que lo contiene como confiable y prefiere ejecutarlo en macOS cuando manejes cuentas sensibles.

Los valores de configuración establecidos mediante mcp-telegram config set (claves API, credenciales de Telegram) siguen el mismo backend: Llavero en macOS, JSON en texto plano en Linux/Windows.

Licencia

MIT