MCP Telegram Poc

🚀 MCP Integration Example with Telegram

A Python-based Model Context Protocol (MCP) client and server that enables LLMs to send notifications via Telegram and receive user responses.

🚀 Quick Start

This project provides a Python-based solution that allows LLMs to interact with users through Telegram. It separates the LLM's reasoning from external operations, offering a more modular and secure way to execute tasks.

✨ Features

• Send text alerts with customizable priority levels to Telegram chats.
• Check user responses and configure timeout periods.
• Flexible templates support integration with MCP-compatible LLM applications.

📊 Comparison between MCP and Function Calls or Agent Tools

MCP Protocol (Model Context Protocol)

• Separates the LLM's inference ("context") from the execution of its external operations. For example, the LLM decides what action to take, while the MCP server handles how to execute that action.
• This decoupling means you can update or replace external tools without changing the core LLM model or its prompts.
• It also allows operations to be executed in a more secure and controlled manner.

LLM Function Calls or Agents

• Direct function calls or agent-based approaches typically mix decision-making with execution logic, which can make the system less modular.
• Changing the way operations are executed may require refactoring the agent or modifying the LLM's prompts, making maintenance more difficult.

📦 Installation

Prerequisites

• Python 3.11 or higher.
• A Telegram bot token (obtained from @BotFather).
• Your Telegram chat ID.

Steps

1. Clone the repository:

   git git@github.com:arananet/mcp-telegram-poc.git
   cd mcp-telegram-poc
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Create a virtual environment:

   python3 -m venv .venv
   

4. Copy .env.example to .env and fill in your Telegram credentials:

   cp .env.example .env
   nano .env
   

⚙️ Configuration

Edit the .env file and fill in the following information:

• TELEGRAM_BOT_TOKEN = Your bot token.
• TELEGRAM_CHAT_ID = Your chat ID.
• OPENAI_API_KEY = Your OpenAI API key.

Obtaining a Telegram Bot Token

1. Chat with @BotFather on Telegram.
2. Send /newbot, provide a name (e.g., mcp_example), and then a username (e.g., mcp_example_bot). BotFather will then reply with your token.
3. Copy the provided token.

Obtaining Your Chat ID

1. Send a message to your bot (go to the created bot page and send a sample message, e.g., hi).
2. Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates.
3. Look for the id field in the chat object. You'll see something like ("chat":{"id": "", ...}). Extract <Your Chat ID>.

💻 Usage Examples

Basic Usage

Running the Server

python3 -m mcp_server

Sending an Alert

python3 -c "from mcp_client import send_alert; send_alert('This is a test alert!')"

Advanced Usage

# Advanced scenarios can be further customized based on specific needs
from mcp_client import send_alert

send_alert("The system has detected an abnormal situation, please note!")

📚 Documentation

Available Tools

send_alert

Sends an alert to a Telegram chat.

Parameters

• message (str): The message to be sent.

Example

from mcp_client import send_alert

send_alert("The system has detected an abnormal situation, please note!")

check_reply

Checks the user's reply to a message.

Parameters

• message_id (int): The ID of the message.
• timeout (int, optional): The time to wait for a reply (in seconds). Default: 30.

Returns

• str: The user's reply or an empty string after a timeout.

📄 License

This project is licensed under the MIT License.

📖 Development Information

• Project Documentation: MCP Integration with Telegram
• Issue Reporting: Submit bugs or suggestions on GitHub Issues.