Telegram MCP Server

Es un servidor MCP que permite enviar y recibir mensajes de Telegram desde clientes MCP (Model Context Protocol) como Gemini Spark o Claude Desktop.

Requisitos previos

Se requiere Node.js para su funcionamiento.

1. Instalación de Node.js:

   • Si aún no está instalado, descargue e instale la versión LTS desde el sitio oficial de Node.js.

   • Tras completar la instalación, reinicie el símbolo del sistema o PowerShell y verifique que node -v y npm -v funcionan.

2. Creación del bot de Telegram:

   • Busque @BotFather dentro de la aplicación de Telegram y cree un nuevo bot con el comando /newbot.

   • Anote el HTTP API Token que se muestra tras la creación (p. ej.: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).

Related MCP server: Telegram MCP Server

Pasos de configuración

1. Acceda al directorio del repositorio e instale las dependencias:

npm install

2. Configuración de las variables de entorno:

   • Copie .env.example del directorio a .env.

copy .env.example .env

• Abra el archivo .env y configure el TELEGRAM_BOT_TOKEN que anotó.

TELEGRAM_BOT_TOKEN=ここにBotのトークンを貼り付け
TELEGRAM_DEFAULT_CHAT_ID=（任意）デフォルトの宛先チャットID

※ Si especifica TELEGRAM_DEFAULT_CHAT_ID, cuando se omita el ID de chat al llamar a una herramienta, el mensaje se enviará automáticamente a ese chat.

3. Ejecución de la compilación: Compile TypeScript a JavaScript.

npm run build

Inicio del servidor y registro en el cliente MCP

1. Inicio del servidor

Para iniciarlo localmente, tras instalar las dependencias y compilar, ejecútelo de la siguiente manera.

npm start

Por defecto, el servidor se inicia en el puerto 3000 y los siguientes endpoints están disponibles.

• Endpoint SSE: http://localhost:3000/sse

Si desea cambiar el número de puerto, inicie el servidor especificando la variable de entorno PORT o añada PORT=8080 al archivo .env.

2. Registro en el cliente MCP

En el caso de Claude Desktop

Añada el servidor SSE al archivo de configuración (p. ej.: AppData\Roaming\Claude\claude_desktop_config.json) de la siguiente manera.

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

En el caso de clientes como Gemini Spark

En la pantalla de configuración del cliente, seleccione el transporte SSE y regístrelo especificando http://localhost:3000/sse como URL.

Herramientas proporcionadas

1. telegram_get_me

• Descripción: Obtiene la información de la cuenta del propio bot. Es útil para probar la conexión.

• Parámetros: Ninguno

2. telegram_send_message

• Descripción: Envía un mensaje al chat_id especificado.

• Parámetros:

  • text (string, obligatorio): El mensaje a enviar.

  • chat_id (string, opcional): El ID de chat de destino o nombre de usuario (p. ej.: @my_channel). Si no se especifica, se utiliza el ID predeterminado de .env.

  • parse_mode (string, opcional): Modo de formato (elija entre Markdown, HTML, MarkdownV2).

3. telegram_get_updates

• Descripción: Obtiene los mensajes (actualizaciones) más recientes dirigidos al bot.

• Parámetros:

  • offset (number, opcional): El ID de actualización que indica la posición de inicio de la obtención.

  • limit (number, opcional): Número máximo de elementos a obtener de una vez (1-100, por defecto 100).

  • timeout (number, opcional): Segundos de tiempo de espera del long polling.