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.

Related MCP server: telegram-mcp

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 .