Telegram MCP-Server
🤖 MCP in Aktion
Hier ist eine Demonstration der Telegram MCP-Funktionen in Claude :
Grundlegendes Anwendungsbeispiel:
Beispiel: Claude bitten, den Chatverlauf zu analysieren und eine Antwort zu senden:
Nachricht erfolgreich an die Gruppe gesendet:
Wie Sie sehen, kann die KI nahtlos mit Ihrem Telegram-Konto interagieren und Ihre Chats, Nachrichten und andere Daten auf natürliche Weise abrufen und anzeigen.
Eine voll funktionsfähige Telegram-Integration für Claude, Cursor und alle MCP-kompatiblen Clients, basierend auf Telethon und dem Model Context Protocol (MCP) . Dieses Projekt ermöglicht Ihnen die programmgesteuerte Interaktion mit Ihrem Telegram-Konto und automatisiert alles vom Messaging bis zur Gruppenverwaltung.
🚀 Funktionen und Tools
Dieser MCP-Server stellt eine große Auswahl an Telegram-Tools bereit. Alle wichtigen Telegram/Telethon-Funktionen sind als Tool verfügbar!
Chat- und Gruppenverwaltung
get_chats(Seite, Seitengröße) : Paginierte Liste der Chats
list_chats(chat_type, limit) : Chats mit Metadaten und Filterung auflisten
get_chat(chat_id) : Detaillierte Informationen zu einem Chat
create_group(title, user_ids) : Eine neue Gruppe erstellen
create_channel(title, about, megagroup) : Einen Kanal oder eine Supergruppe erstellen
edit_chat_title(chat_id, title) : Chat-/Gruppen-/Kanaltitel ändern
delete_chat_photo(chat_id) : Chat-/Gruppen-/Kanalfoto entfernen
leave_chat(chat_id) : Eine Gruppe oder einen Kanal verlassen
get_participants(chat_id) : Listet alle Teilnehmer auf
get_admins(chat_id) : Listet alle Administratoren auf
get_banned_users(chat_id) : Listet alle gesperrten Benutzer auf
promote_admin(chat_id, user_id) : Benutzer zum Administrator befördern
demote_admin(chat_id, user_id) : Degradiert den Administrator zum Benutzer
ban_user(chat_id, user_id) : Benutzer sperren
unban_user(chat_id, user_id) : Benutzersperre aufheben
get_invite_link(chat_id) : Einladungslink abrufen
export_chat_invite(chat_id) : Einladungslink exportieren
import_chat_invite(hash) : Dem Chat per Einladungs-Hash beitreten
join_chat_by_link(Link) : Tritt dem Chat per Einladungslink bei
Nachrichten
get_messages(chat_id, page, page_size) : Paginierte Nachrichten
list_messages(chat_id, limit, search_query, from_date, to_date) : Gefilterte Nachrichten
send_message(chat_id, message) : Senden Sie eine Nachricht
reply_to_message(chat_id, message_id, text) : Auf eine Nachricht antworten
edit_message(chat_id, message_id, new_text) : Bearbeiten Sie Ihre Nachricht
delete_message(chat_id, message_id) : Löscht eine Nachricht
forward_message(from_chat_id, message_id, to_chat_id) : Leitet eine Nachricht weiter
pin_message(chat_id, message_id) : Eine Nachricht anheften
unpin_message(chat_id, message_id) : Eine Nachricht lösen
mark_as_read(chat_id) : Alle als gelesen markieren
get_message_context(chat_id, message_id, context_size) : Kontext rund um eine Nachricht
get_history(chat_id, limit) : Vollständiger Chatverlauf
get_pinned_messages(chat_id) : Listet angeheftete Nachrichten auf
get_last_interaction(contact_id) : Neueste Nachricht mit einem Kontakt
Kontaktverwaltung
list_contacts() : Listet alle Kontakte auf
search_contacts(query) : Kontakte suchen
add_contact(Telefon, Vorname, Nachname) : Einen Kontakt hinzufügen
delete_contact(user_id) : Einen Kontakt löschen
block_user(user_id) : Einen Benutzer blockieren
unblock_user(user_id) : Entsperren Sie einen Benutzer
import_contacts(Kontakte) : Massenimport von Kontakten
export_contacts() : Alle Kontakte als JSON exportieren
get_blocked_users() : Listet blockierte Benutzer auf
get_contact_ids() : Listet alle Kontakt-IDs auf
get_direct_chat_by_contact(contact_query) : Direkten Chat mit einem Kontakt finden
get_contact_chats(contact_id) : Listet alle Chats mit einem Kontakt auf
Benutzer und Profil
get_me() : Holen Sie sich Ihre Benutzerinformationen
update_profile(Vorname, Nachname, Info) : Aktualisieren Sie Ihr Profil
delete_profile_photo() : Entfernen Sie Ihr Profilfoto
get_user_photos(user_id, limit) : Profilfotos eines Benutzers abrufen
get_user_status(user_id) : Ruft den Online-Status eines Benutzers ab
Medien
get_media_info(chat_id, message_id) : Informationen zu Medien in einer Nachricht abrufen
Suche und Entdeckung
search_public_chats(Abfrage) : Öffentliche Chats/Kanäle/Bots durchsuchen
search_messages(chat_id, query, limit) : Nachrichten in einem Chat suchen
resolve_username(Benutzername) : Löst einen Benutzernamen in eine ID auf
Sticker, GIFs, Bots
get_sticker_sets() : Listet Sticker-Sets auf
get_bot_info(bot_username) : Informationen über einen Bot abrufen
set_bot_commands(bot_username, commands) : Bot-Befehle festlegen (nur Bot-Konten)
Datenschutz, Einstellungen und Sonstiges
get_privacy_settings() : Datenschutzeinstellungen abrufen
set_privacy_settings(key, allow_users, disallow_users) : Datenschutzeinstellungen festlegen
mute_chat(chat_id) : Benachrichtigungen stummschalten
unmute_chat(chat_id) : Stummschaltung von Benachrichtigungen aufheben
archive_chat(chat_id) : Einen Chat archivieren
unarchive_chat(chat_id) : Einen Chat aus dem Archiv nehmen
get_recent_actions(chat_id) : Aktuelle Administratoraktionen abrufen
Entfernte Funktionalität
Bitte beachten Sie, dass Tools, die direkten Dateipfadzugriff auf dem Server benötigen ( send_file
, download_media
, set_profile_photo
, edit_chat_photo
, send_voice
, send_sticker
, upload_file
), aus main.py
entfernt wurden. Dies liegt an Einschränkungen in der aktuellen MCP-Umgebung hinsichtlich der Verarbeitung von Dateianhängen und lokalen Dateisystempfaden.
Darüber hinaus wurden GIF-bezogene Tools ( get_gif_search
, get_saved_gifs
, send_gif
) aufgrund anhaltender Zuverlässigkeitsprobleme in der Telethon-Bibliothek oder bei Telegram-API-Interaktionen entfernt.
📋 Voraussetzungen
Python 3.10+
Claude Desktop oder Cursor (oder ein beliebiger MCP-Client)
🔧 Installation und Einrichtung
1. Fork & Clone
2. Erstellen Sie eine virtuelle Umgebung
3. Generieren Sie eine Sitzungszeichenfolge
Folgen Sie den Anweisungen zur Authentifizierung und Aktualisierung Ihrer .env
Datei.
4. Konfigurieren Sie .env
Kopieren Sie .env.example
nach .env
und geben Sie Ihre Werte ein:
Holen Sie sich Ihre API-Anmeldeinformationen unter my.telegram.org/apps .
🐳 Ausführen mit Docker
Wenn Sie Docker und Docker Compose installiert haben, können Sie den Server in einem Container erstellen und ausführen, was die Abhängigkeitsverwaltung vereinfacht.
1. Erstellen Sie das Image
Erstellen Sie das Docker-Image aus dem Stammverzeichnis des Projekts:
2. Ausführen des Containers
Sie haben zwei Möglichkeiten:
Option A: Verwenden von Docker Compose (empfohlen für die lokale Verwendung)
Diese Methode verwendet die Datei docker-compose.yml
und liest Ihre Anmeldeinformationen automatisch aus einer .env
Datei.
.env
Stellen Sie sicher, dass Sie im Projektstamm eine.env
Datei mit IhrenTELEGRAM_API_ID
,TELEGRAM_API_HASH
undTELEGRAM_SESSION_STRING
(oderTELEGRAM_SESSION_NAME
) haben. Verwenden Sie.env.example
als Vorlage.Compose ausführen:
docker compose up --buildVerwenden Sie
docker compose up -d
um im getrennten Modus (Hintergrund) auszuführen.Drücken Sie
Ctrl+C
, um den Server zu stoppen.
Option B: Verwenden von
Sie können den Container direkt ausführen und Anmeldeinformationen als Umgebungsvariablen übergeben.
Ersetzen Sie Platzhalter durch Ihre tatsächlichen Anmeldeinformationen.
Verwenden Sie
-e TELEGRAM_SESSION_NAME=your_session_file_name
anstelle vonTELEGRAM_SESSION_STRING
, wenn Sie dateibasierte Sitzungen bevorzugen (erfordert Volume-Mounting, siehedocker-compose.yml
für ein Beispiel).Die
-it
-Flags sind für die Interaktion mit dem Server von entscheidender Bedeutung.
⚙️ Konfiguration für Claude & Cursor
MCP-Konfiguration
Bearbeiten Sie Ihre Claude-Desktopkonfiguration (z. ~/Library/Application Support/Claude/claude_desktop_config.json
) oder Cursorkonfiguration ( ~/.cursor/mcp.json
):
📝 Tool-Beispiele mit Code und Ausgabe
Nachfolgend finden Sie Beispiele der am häufigsten verwendeten Tools mit ihrer Implementierung und Beispielausgabe.
Erhalten Sie Ihre Chats
Beispielausgabe:
Senden von Nachrichten
Beispielausgabe:
Chat-Einladungslinks erhalten
Die Funktion get_invite_link
ist mit mehreren Fallback-Methoden besonders robust:
Beispielausgabe:
Chats über Einladungslinks beitreten
Beispielausgabe:
Öffentliche Chats durchsuchen
Beispielausgabe:
Direkte Chats mit Kontakten
Beispielausgabe:
🎮 Anwendungsbeispiele
„Meine letzten Chats anzeigen“
„Senden Sie ‚Hallo Welt‘ an Chat 123456789“
„Kontakt mit Telefonnummer +1234567890, Name John Doe hinzufügen“
„Erstellen Sie eine Gruppe ‚Projektteam‘ mit den Benutzern 111, 222, 333“
„Laden Sie die Medien aus Nachricht 42 im Chat 123456789 herunter.“
„Benachrichtigungen für Chat 123456789 stummschalten“
„Benutzer 111 zum Administrator in der Gruppe 123456789 befördern“
„Suche nach öffentlichen Kanälen zum Thema ‚Nachrichten‘“
„Treten Sie der Telegram-Gruppe mit dem Einladungslink https://t.me/+AbCdEfGhIjK bei“
„Sende einen Sticker an meine gespeicherten Nachrichten“
„Holen Sie sich alle meine Sticker-Sets“
Sie können diese Tools in natürlicher Sprache in Claude, Cursor oder jedem MCP-kompatiblen Client verwenden.
🧠 Fehlerbehandlung und Robustheit
Diese Implementierung beinhaltet eine umfassende Fehlerbehandlung:
Sitzungsverwaltung : Funktioniert sowohl mit dateibasierten als auch mit stringbasierten Sitzungen
Fehlerberichterstattung : Detaillierte Fehler werden in
mcp_errors.log
protokolliertGraceful Degradation : Mehrere Fallback-Ansätze für kritische Funktionen
Benutzerfreundliche Meldungen : Klare, umsetzbare Fehlermeldungen anstelle von technischen Fehlern
Kontotyperkennung : Funktionen, die Bot-Konten erfordern, erkennen und benachrichtigen, wenn sie mit Benutzerkonten verwendet werden
Verarbeitung von Einladungslinks : Behandelt verschiedene Linkformate und Fälle, in denen bereits Mitglieder sind
Der Code ist so konzipiert, dass er gegen häufige Probleme und Einschränkungen der Telegram-API robust ist.
🛠️ Beitragsleitfaden
Fork dieses Repo: chigwell/telegram-mcp
Klonen Sie Ihre Gabel:
git clone https://github.com/<your-github-username>/telegram-mcp.gitErstellen Sie einen neuen Zweig:
git checkout -b my-featureNehmen Sie Ihre Änderungen vor und fügen Sie bei Bedarf Tests/Dokumente hinzu.
Pushen und öffnen Sie einen Pull Request an chigwell/telegram-mcp mit einer klaren Beschreibung.
Markieren Sie @chigwell oder @l1v0n1 in Ihrem PR zur Überprüfung.
🔒 Sicherheitsüberlegungen
Übergeben Sie niemals Ihre
Die Sitzungszeichenfolge gewährt vollen Zugriff auf Ihr Telegram-Konto – bewahren Sie es sicher auf!
Die gesamte Verarbeitung erfolgt lokal; es werden keine Daten an andere Orte als die API von Telegram gesendet.
Verwenden Sie
.env.example
als Vorlage und halten Sie Ihre eigentliche.env
Datei privat.Testdateien werden in
.gitignore
automatisch ausgeschlossen.
🛠️ Fehlerbehebung
Überprüfen Sie die Protokolle in Ihrem MCP-Client (Claude/Cursor) und im Terminal auf Fehler.
Detaillierte Fehlerprotokolle finden Sie in
mcp_errors.log
.Interpreterfehler? Stellen Sie sicher, dass Ihre
.venv
erstellt und ausgewählt ist.Datenbanksperre? Verwenden Sie die Sitzungszeichenfolgen-Authentifizierung, keine dateibasierten Sitzungen.
Probleme mit iCloud/Dropbox? Verschieben Sie Ihr Projekt in einen lokalen Pfad ohne Leerzeichen, wenn merkwürdige Fehler auftreten.
Generieren Sie die Sitzungszeichenfolge neu , wenn Sie Ihr Telegrammkennwort ändern oder Authentifizierungsfehler sehen.
Nur-Bot-Funktionen zeigen bei Verwendung mit regulären Benutzerkonten klare Meldungen an.
Fehler beim Testskript? Überprüfen Sie die Testkonfiguration in
.env
auf gültige Testkonten/-gruppen.
📄 Lizenz
Dieses Projekt ist unter der Apache 2.0-Lizenz lizenziert.
🙏 Danksagung
Betreut von
Sternengeschichte
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Ein Server, der die Interaktion mit Telegram-Chats direkt über MCP-kompatible Hosts wie Claude für Desktop ermöglicht und Tools zum Abrufen von Chats, Empfangen und Senden von Nachrichten bereitstellt.
- 🤖 MCP in Aktion
- 🚀 Funktionen und Tools
- Entfernte Funktionalität
- 📋 Voraussetzungen
- 🔧 Installation und Einrichtung
- 🐳 Ausführen mit Docker
- ⚙️ Konfiguration für Claude & Cursor
- 📝 Tool-Beispiele mit Code und Ausgabe
- 🎮 Anwendungsbeispiele
- 🧠 Fehlerbehandlung und Robustheit
- 🛠️ Beitragsleitfaden
- 🔒 Sicherheitsüberlegungen
- 🛠️ Fehlerbehebung
- 📄 Lizenz
- 🙏 Danksagung
- Sternengeschichte
Related MCP Servers
- -securityFlicense-qualityAn MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.Last updated -838
- AsecurityAlicenseAqualityA bridge allowing Claude Desktop to access Telegram chats and messages via the Model Context Protocol, providing read-only capabilities to retrieve dialogs and messages from Telegram.Last updated -2145MIT License
- AsecurityAlicenseAqualityAn MCP server that enables saving and sharing Claude Desktop conversations, allowing users to store chats privately or make them public through a web interface.Last updated -10MIT License
- -securityAlicense-qualityA simple MCP server that allows Claude to access your Telegram account to read and send messages on your behalf.Last updated -6Apache 2.0