Telegram MCP Server 65w

🚀 Telegram MCP Server

A Model Context Protocol (MCP) server that allows large language models to send notifications via Telegram and receive responses from users.

🚀 Quick Start

The Telegram MCP Server is a Model Context Protocol (MCP) server enabling large language models to send notifications via Telegram and receive user responses.

✨ Features

• Send text notifications with customizable urgency levels to Telegram chats.
• Wait for and retrieve user responses.
• Integrate with Cline and other MCP-compatible LLM applications.

📦 Installation

Prerequisites

• Node.js 16 or higher.
• Your Telegram bot token (obtained from @BotFather).
• Your Telegram chat ID.

Installation Methods

Via npm (Recommended)

npm install -g telegram-mcp

Via GitHub

git clone https://github.com/CHarrisTech/telegram-mcp.git
cd telegram-mcp
npm install
npm run build

📚 Documentation

Configuration

The server requires the following two environment variables:

• TELEGRAM_BOT_TOKEN: Your Telegram bot token.
• TELEGRAM_CHAT_ID: Your Telegram chat ID.

Obtaining the Telegram Bot Token

1. Start a conversation with @BotFather on Telegram.
2. Send the command /newbot.
3. Follow the instructions to create a new bot.
4. BotFather will provide you with the new bot token.

Finding Your Chat ID

1. Start a conversation with the new bot.
2. Send a message to the bot.
3. Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates.
4. Find the chat object in the response and note the id field.

Usage

Running Independently

# Set environment variables
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

# Run the server
telegram-mcp

Integrating with Cline

Add the following to your Cline MCP settings file:

{
    "botToken": "your_bot_token",
    "chatId": "your_chat_id"
}

Then run the command:

clarity run mcp-telegram-config.js

Integrating with Clarice Desktop

Add the following to your Clarice Desktop settings file:

{
    "botToken": "your_bot_token",
    "chatId": "your_chat_id"
}

Then run the command:

claride run mcp-telegram-config.js

Available Tools

Sending Notifications

Use the following command to send a notification:

curl -X POST http://localhost:1234/send-notification \
  -H "Content-Type: application/json" \
  -d '{"message": "Example message"}'

Checking Notification Status

Use the following command to check the notification status:

curl -X GET http://localhost:1234/check-notifications

Development Guide

Cloning the Repository

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

Installing Dependencies

npm install

Building the Project

npm run build

Test Script Examples

Linux/MacOS

Create a test.sh file:

#!/bin/bash
set -e

# Set variables
BOT_TOKEN="your_bot_token"
CHAT_ID="your_chat_id"

# Send a notification
curl -X POST http://localhost:1234/send-notification \
  -H "Content-Type: application/json" \
  -d '{"message": "Test message"}'

# Check the notification status
curl -X GET http://localhost:1234/check-notifications

Then run:

chmod +x test.sh
./test.sh

Windows

Create a test.bat file:

@echo off
set BOT_TOKEN=your_bot_token
set CHAT_ID=your_chat_id

curl -X POST http://localhost:1234/send-notification ^
  -H "Content-Type: application/json" ^
  -d '{"message": "Test message"}'

curl -X GET http://localhost:1234/check-notifications

Then run:

test.bat

💻 Usage Examples

Program Example

Create an example.js file:

const TelegramMCP = require('telegram-mcp');

// Initialize the server
const server = new TelegramMCP({
    botToken: 'your_bot_token',
    chatId: 'your_chat_id'
});

// Send a message
server.sendNotification("This is a test message.");

Then run:

node example.js

📄 License

This project is licensed under the MIT license.