Telegram MCP Server

Servidor MCP para interactuar con Telegram a través de la API de Telegram Bot. El servidor proporciona al cliente LLM un conjunto de herramientas para enviar mensajes, leer los últimos mensajes disponibles y obtener información del chat.

Funcionalidades

El servidor proporciona tres herramientas MCP:

• send_message — envía un mensaje de texto a un chat de Telegram especificado.

• get_recent_messages — obtiene los últimos mensajes disponibles de un chat especificado.

• get_chat_info — devuelve información básica sobre un chat de Telegram.

El servidor utiliza transporte stdio, por lo que se puede conectar a MCP Inspector y otros clientes MCP sin un servidor HTTP independiente.

Related MCP server: agent-telegram-mcp

Arquitectura

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py se encarga de la interfaz MCP y el registro de herramientas.

telegram_client.py encapsula la interacción HTTP con la API de Telegram Bot.

config.py carga el token desde la variable de entorno.

Stack

• Python 3.10+

• MCP Python SDK 2.x

• API de Telegram Bot

• httpx

• python-dotenv

Estructura del proyecto

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Requisitos

• Python 3.10 o superior

• Bot de Telegram creado a través de @BotFather

• Node.js y npx — solo si se usa MCP Inspector mediante mcp dev

Instalación

Clone el repositorio y acceda a su directorio:

git clone <repository-url>
cd telegram-mcp

Cree un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate

Instale las dependencias:

pip install -r requirements.txt

Configuración del bot de Telegram

1. Abra Telegram y busque @BotFather.

2. Ejecute /newbot.

3. Cree el bot y obtenga el token de la API de Bot.

4. No agregue el token al código fuente ni a Git.

Cree un archivo .env:

cp .env.example .env

Indique el token:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env está agregado a .gitignore.

Preparación del chat

Chat personal

1. Abra el bot creado.

2. Presione Start o envíele un mensaje.

3. Para verificar get_recent_messages, envíe varios mensajes de texto.

Grupo

1. Cree un grupo de prueba.

2. Agregue el bot al grupo.

3. Si el bot debe ver los mensajes normales del grupo, desactive el modo de privacidad a través de @BotFather (/setprivacy → Disable).

4. Envíe varios mensajes al grupo.

Para obtener el chat_id, es conveniente llamar primero a get_chat_info o get_recent_messages después de que el bot haya recibido un mensaje del chat deseado.

Ejecución

Desde el directorio raíz del proyecto:

python src/server.py

El servidor funciona a través de stdio y espera una conexión MCP. Por lo tanto, la ausencia de salida normal en la terminal después del inicio es un comportamiento normal.

Para desarrollo y verificación, se puede usar la CLI de MCP:

mcp dev src/server.py

El comando inicia el servidor y MCP Inspector. Inspector usa npx, por lo que Node.js debe estar disponible en PATH.

Herramientas MCP

send_message

Envía un mensaje de texto a Telegram.

Parámetros:

chat_id: string — ID чата
text: string — текст сообщения

Ejemplo:

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

El servidor devuelve una confirmación de envío y el message_id.

get_recent_messages

Obtiene los últimos mensajes disponibles de un chat especificado.

Parámetros:

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit está limitado al rango de 1 a 100.

Ejemplo:

chat_id: 123456789
limit: 10

El resultado contiene el remitente y el texto de cada mensaje disponible.

get_chat_info

Obtiene información básica sobre un chat.

Parámetros:

chat_id: string — ID чата

La respuesta muestra los campos disponibles, incluyendo ID, tipo, nombre, username, nombre y apellido.

Cómo funciona la obtención de mensajes

La API de Telegram Bot no proporciona al bot un método separado para leer el historial arbitrario del chat. Para recibir mensajes entrantes, el servidor usa getUpdates.

get_recent_messages solicita hasta 100 de las últimas actualizaciones disponibles y luego las filtra por chat_id. Por lo tanto, la herramienta trabaja con los mensajes que Telegram proporciona al bot a través de la cola de actualizaciones, no con el historial completo del chat.

Esto significa que la herramienta no reemplaza a un cliente de Telegram con acceso a todo el historial de la conversación. Para pruebas, es suficiente enviar mensajes después de agregar el bot al chat y luego llamar a get_recent_messages.

Importante: getUpdates no se usa simultáneamente con un webhook activo. Si el bot tiene configurado un webhook, elimínelo primero para que el long polling a través de getUpdates pueda recibir actualizaciones.

Escenario de ejemplo

1. Iniciar MCP Inspector.

2. Conectar src/server.py.

3. Asegurarse de que estén disponibles:

   • send_message

   • get_recent_messages

   • get_chat_info

4. Llamar a get_chat_info para verificar la conexión al chat.

5. Llamar a send_message y verificar que el mensaje aparezca en Telegram.

6. Enviar varios mensajes en Telegram.

7. Llamar a get_recent_messages y verificar la lista de mensajes obtenida.

Seguridad

El token de la API de Telegram Bot se transmite únicamente a través de la variable de entorno TELEGRAM_BOT_TOKEN.

El archivo .env real no debe incluirse en Git. En el repositorio solo se almacena .env.example sin un token funcional.

Limitaciones

• El bot no tiene acceso a todo el historial del chat de Telegram a través de la API de Bot.

• get_recent_messages funciona con las actualizaciones de bot disponibles.

• En grupos, el conjunto de mensajes que recibe el bot depende de la configuración de privacidad de Telegram.

• getUpdates y webhook son formas mutuamente excluyentes de recibir actualizaciones.