MCP Integration example with Telegram

by arananet

225 downloads Not rated yet MIT license

GitHub

Communication

About

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

Details

License: MIT license

Explore

- 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 applications

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 Telegram

Command (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

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp integration example with telegram": {
            "mcp-telegram-poc": {
                "command": "python3",
                "args": [
                    "-m",
                    "venv",
                    ".venv"
                ]
            }
        }
    }
}

From the repository

- Python 3.11+
- A Telegram bot token (from @BotFather)
- Your Telegram chat ID

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.

python3 src/mcp_handler.py

For testing sending and receiving an alert:

python3 examples/test_client.py

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"
        ]
    }
}

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 applications

MCP 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 ID

Installation

1. Clone the repository:

   git [email protected]:arananet/mcp-telegram-poc.git
   cd mcp-telegram-poc

2. Install dependencies:

   pip install -r requirements.txt

3. Create the 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 .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. Visit https://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 framework

python3 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

The examples 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 Arana

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Features

MCP vs Function Calls or Agent tools

MCP Protocol (Model Context Protocol):

LLM Function Call or Agent:

Prerequisites

Installation

Configuration

Getting a Telegram Bot Token

Finding Your Chat ID

Usage

Running Standalone

Programmatic Usage

Agent integration

Testing Locally

Available Tools

send_alert

check_reply

Development

Examples

Developer

More like this

Slack

Inbox Zero

Production-ready MCP integrations for AI applications

whatsapp-mcp

`send_alert`

`check_reply`