Servidor MCP de Telegram

Un servidor para interactuar con Telegram a través de la API MTProto, que requiere credenciales de API.

GitHub

186

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Telegram

Acerca de

El servidor es un puente entre la API de Telegram y los asistentes de IA, y se basa en el Model Context Protocol.

[!IMPORTANT] Asegúrate de haber leído y comprendido los Términos de Servicio de la API de Telegram antes de usar este servidor. Cualquier uso indebido de la API de Telegram puede resultar en la suspensión de tu cuenta.

¿Qué es MCP?

El Model Context Protocol (MCP) es un sistema que permite que las aplicaciones de IA, como Claude Desktop, se conecten a herramientas externas y fuentes de datos. Proporciona una forma clara y segura para que los asistentes de IA trabajen con servicios locales y APIs, manteniendo al usuario en control.

¿Qué hace este servidor?

Por ahora, el servidor proporciona acceso de solo lectura a la API de Telegram.

Obtener la lista de diálogos (chats, canales, grupos)
Obtener la lista de mensajes (no leídos) en el diálogo dado
Marcar canal como leído
Recuperar mensajes por fecha y hora
Descargar archivos multimedia
Obtener la lista de contactos
Redactar un mensaje
...

Casos de uso prácticos

Crear un resumen de los mensajes no leídos
Encontrar contactos con cumpleaños próximos y programar un saludo
Encontrar discusiones sobre un tema dado, resumirlas y proporcionar una lista de enlaces

Requisitos previos

Herramienta uv

Instalación

uv tool install git+https://github.com/sparfenyuk/mcp-telegram

[!NOTE] Si ya has instalado el servidor, puedes actualizarlo usando el comando uv tool upgrade --reinstall.

[!NOTE] Si quieres eliminar el servidor, usa el comando uv tool uninstall mcp-telegram.

Configuración

Configuración de la API de Telegram

Antes de poder usar el servidor, necesitas conectarte a la API de Telegram.

Obtén el ID de API y el hash desde API de Telegram
Ejecuta el siguiente comando:
```
mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
```
Ingresa el código que recibiste de Telegram para conectarte a la API.

La contraseña puede ser requerida si tienes la autenticación de dos factores habilitada.

[!NOTE] Para cerrar sesión en la API de Telegram, usa el comando mcp-telegram logout.

Configuración de Claude Desktop

Configura Claude Desktop para que reconozca el servidor Exa MCP.

Abre el archivo de configuración de Claude Desktop:
- en MacOS, el archivo de configuración se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json
- en Windows, el archivo de configuración se encuentra en %APPDATA%\Claude\claude_desktop_config.json
Nota: También puedes encontrar claude_desktop_config.json dentro de la configuración de la aplicación Claude Desktop

Añade la configuración del servidor

{
  "mcpServers": {
    "mcp-telegram": {
        "command": "mcp-server",
        "env": {
          "TELEGRAM_API_ID": "<your-api-id>",
          "TELEGRAM_API_HASH": "<your-api-hash>",
        },
      }
    }
  }
}

Configuración de Telegram

Antes de trabajar con la API de Telegram, necesitas obtener tu propio ID de API y hash:

Inicia sesión en tu cuenta de Telegram con el número de teléfono de la cuenta de desarrollador que vayas a usar.
Haz clic en API Development tools.
Aparecerá una ventana 'Create new application'. Completa los detalles de tu aplicación. No es necesario ingresar ninguna URL, y solo los dos primeros campos (App title y Short name) pueden modificarse más adelante.
Haz clic en 'Create application' al final. Recuerda que tu hash de API es secreto y Telegram no te permitirá revocarlo. ¡No lo publiques en ningún lugar!

Desarrollo

Primeros pasos

Clona el repositorio
Instala las dependencias
```
uv sync
```
Ejecuta el servidor
```
uv run mcp-telegram --help
```

Se pueden añadir herramientas al archivo src/mcp_telegram/tools.py.

Cómo añadir una nueva herramienta:

Crea una nueva clase que herede de ToolArgs
```
class NewTool(ToolArgs):
    """Description of the new tool."""
    pass
```
Los atributos de la clase se usarán como argumentos para la herramienta. El docstring de la clase se usará como descripción de la herramienta.
Implementa la función tool_runner para la nueva clase
```
@tool_runner.register
async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]:
    pass
```
La función debe devolver una secuencia de TextContent, ImageContent o EmbeddedResource. La función debe ser asíncrona y aceptar un único argumento de la nueva clase.
¡Listo! Reinicia el cliente y la nueva herramienta debería estar disponible.

La validación se puede realizar a través de Claude Desktop o ejecutando la herramienta directamente.

Depuración del servidor en terminal

Para ejecutar la herramienta directamente, usa el siguiente comando:


# List all available tools
uv run cli.py list-tools

# Run the concrete tool
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

Depuración del servidor en el Inspector

El inspector de MCP es una herramienta que ayuda a depurar el servidor usando una interfaz de usuario elegante. Para ejecutarlo, usa el siguiente comando:

npx @modelcontextprotocol/inspector uv run mcp-telegram

[!WARNING] No olvides definir las variables de entorno TELEGRAM_API_ID y TELEGRAM_API_HASH en el inspector.

Solución de problemas

Mensaje 'Could not connect to MCP server mcp-telegram'

Si ves el mensaje 'Could not connect to MCP server mcp-telegram' en Claude Desktop, significa que la configuración del servidor es incorrecta.

Prueba lo siguiente:

Usa la ruta completa al binario uv en el archivo de configuración
Verifica la ruta al repositorio clonado en el archivo de configuración