Servidor MCP de Telegram

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 Protocolo de Contexto de Modelo .

[!IMPORTANTE] Asegúrate de leer y comprender 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 Protocolo de Contexto de Modelo (MCP) es un sistema que permite que las aplicaciones de IA, como Claude Desktop, se conecten a herramientas y fuentes de datos externas. Ofrece una forma clara y segura para que los asistentes de IA trabajen con servicios y API locales, manteniendo al usuario en control.

¿Qué hace este servidor?

Hasta el momento, el servidor proporciona acceso de solo lectura a la API de Telegram.

[x] Obtener la lista de diálogos (chats, canales, grupos)
[x] Obtener la lista de mensajes (no leídos) en el cuadro de 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

[x] Crear un resumen de los mensajes no leídos
[ ] Encuentra contactos con próximos cumpleaños y programa un saludo
[ ] Encuentre discusiones sobre un tema determinado, resúmalas y proporcione una lista de enlaces.

Prerrequisitos

herramienta uv

Instalación

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

[!NOTA] Si ya ha instalado el servidor, puede actualizarlo utilizando el comando uv tool upgrade --reinstall .

[!NOTA] Si desea eliminar el servidor, utilice el comando de la uv tool uninstall mcp-telegram .

Configuración

Configuración de la API de Telegram

Antes de poder utilizar el servidor, debe conectarse a la API de Telegram.

Obtenga el ID de API y el hash de la API de Telegram
Ejecute 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.Es posible que se requiera la contraseña si tiene habilitada la autenticación de dos factores.

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

Configuración del escritorio de Claude

Configure Claude Desktop para reconocer el servidor Exa MCP.

Abra 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
Agregar 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:

Inicie sesión en su cuenta de Telegram con el número de teléfono de la cuenta de desarrollador que desea utilizar.
Haga clic en Herramientas de desarrollo de API.
Aparecerá la ventana "Crear nueva aplicación". Complete los datos de su aplicación. No es necesario introducir ninguna URL; por el momento, solo los dos primeros campos (título de la aplicación y nombre corto) se pueden modificar posteriormente.
Haz clic en "Crear aplicación" al final. Recuerda que el hash de tu API es secreto y Telegram no te permitirá revocarlo. ¡No lo publiques en ningún sitio!

Desarrollo

Empezando

Clonar el repositorio
Instalar las dependencias
uv sync
Ejecutar el servidor
uv run mcp-telegram --help

Se pueden agregar herramientas al archivo src/mcp_telegram/tools.py .

Cómo agregar 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. La cadena de documentación de la clase se usará como descripción de la herramienta.
Implementar 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. 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 la terminal

Para ejecutar la herramienta directamente, utilice 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 MCP es una herramienta que ayuda a depurar el servidor mediante una interfaz de usuario sofisticada. Para ejecutarlo, use el siguiente comando:

npx @modelcontextprotocol/inspector uv run mcp-telegram

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

Solución de problemas

Mensaje 'No se pudo conectar al servidor MCP mcp-telegram'

Si ve el mensaje 'No se pudo conectar al servidor MCP mcp-telegram' en Claude Desktop, significa que la configuración del servidor es incorrecta.

Pruebe lo siguiente:

Utilice la ruta completa al binario uv en el archivo de configuración
Verifique la ruta al repositorio clonado en el archivo de configuración

Telegram MCP Server

Integrations