Telegram MCP Server

Telegram MCP-Server

Ein MCP-Server, der KI-Assistenten (wie Claude) die Interaktion mit Ihrem Telegram-Konto über die Benutzer-Client-API (nicht die Bot-API) ermöglicht. Erstellt mit @mtproto/core und dem FastMCP -Framework.

Merkmale

Werkzeuge

• listChannels
  • Listet basierend auf dem Cache des Servers die verfügbaren Telegram-Kanäle/Chats auf, auf die das Konto zugreifen kann.
  • Parameter:
    • limit (Zahl, optional): Maximale Anzahl der zurückzugebenden Kanäle (Standard: 50).
  • Ausgabe: Eine Liste von Kanälen/Chats mit ihrer ID, ihrem Titel, ihrem Typ und ihrem Zugriffs-Hash (falls zutreffend).
• searchChannels
  • Durchsucht die zwischengespeicherten Kanäle/Chats nach Schlüsselwörtern in ihren Namen.
  • Parameter:
    • keywords (Zeichenfolge): Schlüsselwörter, nach denen in Kanalnamen gesucht werden soll.
    • limit (Zahl, optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 100).
  • Ausgabe: Eine Liste passender Kanäle/Chats.
• getChannelMessages
  • Ruft aktuelle Nachrichten aus einem bestimmten Kanal/Chat anhand seiner ID ab.
  • Parameter:
    • channelId (Zahl): Die numerische ID des Kanals/Chats (erhalten aus listChannels oder searchChannels ).
    • limit (Zahl, optional): Maximale Anzahl der zurückzugebenden Nachrichten (Standard: 100).
    • filterPattern (Zeichenfolge, optional): Ein JavaScript-kompatibler regulärer Ausdruck zum Filtern von Nachrichten nach ihrem Textinhalt.
  • Ausgabe: Eine Liste von Nachrichten mit ID, Datum, Text und Absender-ID.

Voraussetzungen

1. Node.js: Version 18 oder höher empfohlen.
2. Telegram-Konto:
   • Sie benötigen ein aktives Telegram-Konto.
   • Die Zwei-Schritt-Verifizierung (2FA) muss für Ihr Konto aktiviert sein (Einstellungen → Datenschutz und Sicherheit → Zwei-Schritt-Verifizierung).
3. Telegram-API-Anmeldeinformationen:
   • Erhalten Sie eine api_id und api_hash , indem Sie unter https://core.telegram.org/api/obtaining_api_id eine neue Anwendung erstellen.

Installation

1. Klonen Sie dieses Repository:
   git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL cd telegram-mcp-server
2. Installieren Sie Abhängigkeiten:
   npm install

Konfiguration

Es müssen zwei separate Konfigurationen eingerichtet werden:

1. MCP-Serverkonfiguration:Konfigurieren Sie den Telegram MCP-Server mithilfe von Umgebungsvariablen (in einer .env Datei oder direkt in Ihrer Umgebung):
   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567
   Ersetzen Sie die Platzhalterwerte durch Ihre tatsächlichen Anmeldeinformationen.
2. MCP-Client-Konfiguration:Konfigurieren Sie Client-Software (Claude Desktop, Cursor usw.) für die Verbindung mit dem MCP-Server, indem Sie ihre Konfigurationsdateien ändern:
   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }
   Für Claude Desktop befindet sich die Konfigurationsdatei unter:
   • Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Unter Windows: %APPDATA%/Claude/claude_desktop_config.json

   Wichtig: Starten Sie Ihren MCP-Client neu, um die Änderungen zu übernehmen.

Ausführen des Servers

1. Erstanmeldung (Wichtiger erster Schritt): Wenn Sie den Server zum ersten Mal starten (oder wenn Ihre Sitzung abläuft/ungültig ist), muss er sich bei Telegram authentifizieren. Führen Sie den Server direkt von Ihrem Terminal aus aus:
   npm start
   • Der Server verwendet die Anmeldeinformationen aus Ihrer .env Datei.
   • Sie werden im Terminal aufgefordert, den an Ihr Telegram-Konto gesendeten Anmeldecode und gegebenenfalls Ihr 2FA-Passwort einzugeben.
   • Nach erfolgreicher Anmeldung wird eine Sitzungsdatei ( ./data/session.json ) erstellt. Diese Datei ermöglicht dem Server künftig die automatische Anmeldung ohne Eingabe von Codes/Passwörtern.
   • Der Server versucht außerdem, einen Cache Ihrer Chats ( ./data/dialog_cache.json ) zu erstellen oder zu laden. Dies kann beim ersten Start, insbesondere bei vielen Chats, einige Zeit dauern. Nachfolgende Starts sind schneller, wenn der Cache vorhanden ist.
2. Normalbetrieb: Sie müssen den Server manuell starten, indem Sie npm start im Projektverzeichnis ausführen.Sobald der Server läuft, stellt Ihr MCP-Client (z. B. Claude Desktop) über die in seiner Konfiguration angegebene URL (standardmäßig http://localhost:8080/sse ) eine Verbindung zu ihm her.

Fehlerbehebung

• Anmeldeaufforderungen: Wenn der Server beim Start durch den MCP-Client weiterhin Anmeldecodes/Passwörter anfordert, stellen Sie sicher, dass die Datei data/session.json vorhanden und gültig ist. Möglicherweise müssen Sie npm start einmal manuell ausführen, um die Sitzung zu aktualisieren. Überprüfen Sie außerdem, ob die Dateiberechtigungen dem Benutzer, der den MCP-Client ausführt, das Lesen/Schreiben des data erlauben.
• Cache-Probleme: Wenn Kanäle veraltet oder fehlend erscheinen, können Sie ./data/dialog_cache.json löschen und den Server neu starten ( npm start manuell ausführen), um eine vollständige Aktualisierung zu erzwingen. Dies kann einige Zeit dauern.
• Modul nicht gefunden: Führen Sie npm install unbedingt im Projektverzeichnis aus. Wenn der MCP-Client den Server startet, stellen Sie sicher, dass das Arbeitsverzeichnis korrekt eingestellt ist, oder verwenden Sie absolute Pfade.
• Andere Probleme: Wenn Sie auf andere Probleme stoßen, können Sie gerne ein Problem in diesem Server-Repo öffnen.

Telegram-Client-Bibliothek

Dieses Repository enthält auch die zugrunde liegende Bibliothek telegram-client.js die vom MCP-Server verwendet wird. Details zur direkten Verwendung der Bibliothek (z. B. für benutzerdefinierte Skripte) finden Sie in LIBRARY.md .

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .