Telegram MCP Server

MCP-Server für die Interaktion mit Telegram über die Telegram Bot API. Der Server stellt dem LLM-Client eine Reihe von Tools zum Senden von Nachrichten, Lesen der letzten verfügbaren Nachrichten und Abrufen von Chat-Informationen zur Verfügung.

Funktionen

Der Server bietet drei MCP-Tools:

• send_message – sendet eine Textnachricht an einen angegebenen Telegram-Chat.

• get_recent_messages – ruft die letzten verfügbaren Nachrichten aus einem angegebenen Chat ab.

• get_chat_info – gibt grundlegende Informationen über einen Telegram-Chat zurück.

Der Server verwendet den stdio-Transport, sodass er ohne separaten HTTP-Server an den MCP Inspector und andere MCP-Clients angeschlossen werden kann.

Related MCP server: agent-telegram-mcp

Architektur

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py ist für die MCP-Schnittstelle und die Registrierung der Tools verantwortlich.

telegram_client.py kapselt die HTTP-Interaktion mit der Telegram Bot API.

config.py lädt das Token aus der Umgebungsvariable.

Technologie-Stack

• Python 3.10+

• MCP Python SDK 2.x

• Telegram Bot API

• httpx

• python-dotenv

Projektstruktur

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Voraussetzungen

• Python 3.10 oder neuer

• Ein über @BotFather erstellter Telegram-Bot

• Node.js und npx – nur erforderlich, wenn der MCP Inspector über mcp dev verwendet wird

Installation

Klonen Sie das Repository und wechseln Sie in das Verzeichnis:

git clone <repository-url>
cd telegram-mcp

Erstellen Sie eine virtuelle Umgebung:

python3 -m venv .venv
source .venv/bin/activate

Installieren Sie die Abhängigkeiten:

pip install -r requirements.txt

Einrichtung des Telegram-Bots

1. Öffnen Sie Telegram und suchen Sie nach @BotFather.

2. Führen Sie /newbot aus.

3. Erstellen Sie einen Bot und erhalten Sie den Bot-API-Token.

4. Fügen Sie das Token nicht in den Quellcode oder in Git ein.

Erstellen Sie eine .env-Datei:

cp .env.example .env

Geben Sie das Token an:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env wurde zu .gitignore hinzugefügt.

Vorbereitung des Chats

Privater Chat

1. Öffnen Sie den erstellten Bot.

2. Klicken Sie auf Start oder senden Sie ihm eine Nachricht.

3. Senden Sie einige Textnachrichten, um get_recent_messages zu testen.

Gruppe

1. Erstellen Sie eine Testgruppe.

2. Fügen Sie den Bot zur Gruppe hinzu.

3. Wenn der Bot normale Gruppennachrichten sehen soll, deaktivieren Sie den Privatsphäre-Modus über @BotFather (/setprivacy → Disable).

4. Senden Sie einige Nachrichten in die Gruppe.

Um die chat_id zu erhalten, rufen Sie am besten zuerst get_chat_info oder get_recent_messages auf, nachdem der Bot eine Nachricht aus dem entsprechenden Chat erhalten hat.

Start

Aus dem Stammverzeichnis des Projekts:

python src/server.py

Der Server arbeitet über stdio und wartet auf eine MCP-Verbindung. Daher ist das Fehlen einer normalen Terminalausgabe nach dem Start normales Verhalten.

Für Entwicklung und Tests kann die MCP-CLI verwendet werden:

mcp dev src/server.py

Der Befehl startet den Server und den MCP Inspector. Der Inspector verwendet npx, daher muss Node.js im PATH verfügbar sein.

MCP-Tools

send_message

Sendet eine Textnachricht an Telegram.

Parameter:

chat_id: string — ID чата
text: string — текст сообщения

Beispiel:

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

Der Server gibt eine Bestätigung des Sendens und die message_id zurück.

get_recent_messages

Ruft die letzten verfügbaren Nachrichten des angegebenen Chats ab.

Parameter:

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit ist auf einen Bereich von 1 bis 100 beschränkt.

Beispiel:

chat_id: 123456789
limit: 10

Das Ergebnis enthält den Absender und den Text jeder verfügbaren Nachricht.

get_chat_info

Ruft grundlegende Informationen über einen Chat ab.

Parameter:

chat_id: string — ID чата

Die Antwort zeigt die verfügbaren Felder an, einschließlich ID, Typ, Name, Benutzername, Vor- und Nachname.

Wie der Nachrichtenabruf funktioniert

Die Telegram Bot API bietet dem Bot keine separate Methode zum Lesen einer beliebigen Chat-Historie. Zum Abrufen eingehender Nachrichten verwendet der Server getUpdates.

get_recent_messages fragt bis zu 100 der letzten verfügbaren Updates ab und filtert sie dann nach chat_id. Daher arbeitet das Tool mit Nachrichten, die Telegram dem Bot über die Update-Warteschlange bereitstellt, und nicht mit der vollständigen Chat-Historie.

Das bedeutet, dass das Tool keinen Telegram-Client mit Zugriff auf die gesamte Nachrichtenhistorie ersetzt. Für Tests reicht es aus, Nachrichten zu senden, nachdem der Bot zum Chat hinzugefügt wurde, und dann get_recent_messages aufzurufen.

Wichtig: getUpdates kann nicht gleichzeitig mit einem aktiven Webhook verwendet werden. Wenn für den Bot ein Webhook konfiguriert ist, entfernen Sie ihn zuerst, damit Long Polling über getUpdates Updates empfangen kann.

Beispielszenario

1. Starten Sie den MCP Inspector.

2. Verbinden Sie src/server.py.

3. Stellen Sie sicher, dass folgende Tools verfügbar sind:

   • send_message

   • get_recent_messages

   • get_chat_info

4. Rufen Sie get_chat_info auf, um die Verbindung zum Chat zu überprüfen.

5. Rufen Sie send_message auf und überprüfen Sie, ob die Nachricht in Telegram erscheint.

6. Senden Sie einige Nachrichten in Telegram.

7. Rufen Sie get_recent_messages auf und überprüfen Sie die erhaltene Nachrichtenliste.

Sicherheit

Der Telegram Bot API-Token wird nur über die Umgebungsvariable TELEGRAM_BOT_TOKEN übergeben.

Die echte .env-Datei sollte nicht in Git gelangen. Im Repository wird nur .env.example ohne funktionierendes Token gespeichert.

Einschränkungen

• Der Bot hat über die Bot API keinen Zugriff auf die gesamte Telegram-Chat-Historie.

• get_recent_messages arbeitet mit den verfügbaren Bot-Updates.

• In Gruppen hängt der Satz von Nachrichten, die der Bot erhält, von den Telegram-Datenschutzeinstellungen ab.

• getUpdates und Webhook schließen sich gegenseitig als Methoden zum Empfangen von Updates aus.