MCP Integration example with Telegram
About
A Python-based Model Context Protocol (MCP) client and server that enables LLMs to send notifications via Telegram and receive user responses.
Details
- Author
- arananet
- Downloads
- 225
- Categories
- Communication
Jump to
- Send text alerts to Telegram with customizable urgency levels
- Check for user replies with configurable timeouts
- Integration with MCP‑compatible LLM applications
- Decouples reasoning from execution for safer tool use
- Update external tools without changing LLM prompts
- Supports AutoGen 0.4 framework integration
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MCP Integration example with TelegramCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Clone the repository, install dependencies (pip install -r requirements.txt), create a virtual environment, and fill in your Telegram credentials in a .env file (Telegram bot token, chat ID, OpenAI API key). Run the server with python3 src/mcp_handler.py, or test client interaction with python3 examples/test_client.py. The server exposes two tools: send_alert (sends a Telegram message) and check_reply (polls for replies).
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp integration example with telegram": {
"mcp-telegram-poc": {
"command": "python3",
"args": [
"-m",
"venv",
".venv"
]
}
}
}
}McpServers
{
"mcp-telegram-poc": {
"command": "python3",
"args": [
"-m",
"venv",
".venv"
]
}
}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.
Features
- Send text alerts to a Telegram chat with customizable urgency levels - Check for user replies with configurable timeouts - Flexible template for integration with MCP-compatible LLM applicationsMCP vs Function Calls or Agent tools
MCP Protocol (Model Context Protocol):
- Separates the LLM’s reasoning (the “context”) from the execution of external actions. For example, the LLM decides what action to take and the MCP server handles how to execute that action. - This decoupling means you can update or swap out external tools without changing the core LLM model or its prompts. - It also allows for safer and more controlled execution of actions.LLM Function Call or Agent:
- Direct function calls or agent-based methods often mix decision-making and execution logic, which can make the system less modular. - Changes in how an action is performed may require reengineering the agent or modifying the LLM’s prompts, making maintenance harder.Prerequisites
- Python 3.11+ - A Telegram bot token (from @BotFather) - Your Telegram chat IDInstallation
1. Clone the repository: git git@github.com:arananet/mcp-telegram-poc.git
cd mcp-telegram-poc
pip install -r requirements.txt
python3 -m venv .venv
.env.example to .env and fill in your Telegram credentials:
cp .env.example .env
nano .env
Configuration
Edit.env with:
- TELEGRAM_BOT_TOKEN=your_bot_token_here
- TELEGRAM_CHAT_ID=your_chat_id_here
- OPENAI_API_KEY=your_openai_apikey
Getting a Telegram Bot Token
1. Chat with @BotFather on Telegram. 2. Send/newbot and provide a name (e.g. mcp_example) and then provide an user name (e.g. mcp_example_bot) after this telegram botfather will reply with the token.
3. Copy the token provided.
Finding Your Chat ID
1. Send a message to your bot (go to the created bot and send some example, e.g. hi). 2. Visithttps://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates.
3. Find the chat object's id field. You will see something like this (e.g. "chat":{"id":107184517,"first_name":"Edu","last_name":"Arana"...) the Chat ID is 107184517.
Usage
Running Standalone
python3 src/mcp_handler.py
Programmatic Usage
For testing sending and receiving an alert:python3 examples/test_client.py
Agent integration
For testing the integration of the MCP using an agent with autogen 0.4 frameworkpython3 examples/test_autogen_agent.py
Testing Locally
Use the test script (Linux/macOS):chmod +x test_server.sh
./test_server.sh
Available Tools
send_alert
- Parameters:
- message (str, required): Message to send (Markdown supported).
- project (str, required): Project name.
- urgency (str, optional): "low", "medium", "high" (default: "medium").
- Description: Sends a Telegram alert and waits for a reply.
check_reply
- Parameters:
- message_id (int, required): Message ID to check.
- timeout_seconds (int, optional): Wait time (default: 60).
- Description: Polls for replies to a specific message.
Development
- Install dependencies:pip install -r requirements.txt
- Run server: python3 src/mcp_handler.py
- Test client: python3 examples/test_client.py
- Test Agent: python3 examples/test_autogen_agent.py
Examples
Theexamples folder contains:
- test_server.py: Runs the server standalone.
- test_client.py: Demonstrates client interaction.
- test_autogen_agent.py: Demostrates the MCP integration between an AutoGen Agent
- In the images folder you can find some screenshots of the testings.
Developer
- Eduardo AranaSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
