mcp-telegram

Ein MCP-Server, der KI-Assistenten wie Claude über die User-API (MTProto) mit Ihrem echten Telegram-Konto verbindet. Kein Bot – Claude liest und sendet Nachrichten als Sie.

Erstellt mit gotd/td und dem offiziellen MCP Go SDK.

Telegram API Nutzungsbedingungen: Dieses Projekt verwendet die Telegram User-API. Sie müssen Ihre eigene api_id und api_hash von my.telegram.org beziehen und die Telegram API Nutzungsbedingungen einhalten. Missbrauch der User-API (Spam, Massennachrichten, Scraping) kann zur Sperrung Ihres Kontos führen. Sie sind allein verantwortlich für die Nutzung dieses Tools.

Inhalt

• Funktionen

• Was Sie damit tun können

• Vergleich mit chaindead/telegram-mcp

• Schnellstart

• Client-Konfiguration

• Konfigurationsreferenz

• Sicherheit

Funktionen

Zusätzliche Funktionen:

• Versand von Dateien und Fotos

• Weiterleiten von Nachrichten zwischen Chats

• Antworten auf spezifische Nachrichten

• Herunterladen von Fotos und Dokumenten aus dem Nachrichtenverlauf

• Filtern des Verlaufs nach Datumsbereich (since / until)

• Typisierte Peer-Referenzen (user:ID, chat:ID, channel:ID), um ID-Kollisionen zu vermeiden

• Lazy Peer Resolution – vermeidet FLOOD_WAIT-Fehler beim Start

• Globale Ratenbegrenzung auf RPC-Ebene

Was Sie damit tun können

Sobald die Verbindung hergestellt ist, können Sie Ihren KI-Assistenten Dinge fragen wie:

Nachrichten aufholen

• "Überprüfe meine ungelesenen Telegram-Nachrichten und gib mir eine Zusammenfassung"

• "Was hat @alice in den letzten 24 Stunden geschrieben?"

• "Zeige mir Nachrichten aus dem Dev-Team-Chat seit Montag"

Antworten und kommunizieren

• "Entwirf eine Antwort auf die letzte Nachricht von @bob – sende sie noch nicht ab"

• "Sende 'klingt gut, treffen wir uns um 15 Uhr' an @alice"

• "Antworte auf Nachricht 1234 im Projekt-Chat mit meinem Feedback"

Posteingang verwalten

• "Markiere alle Nachrichten im News-Kanal als gelesen"

• "Welche meiner Whitelist-Chats haben ungelesene Nachrichten?"

• "Lade die Fotos aus den heutigen Nachrichten im Design-Chat herunter"

Recherchieren und analysieren

• "Finde alle Nachrichten, die das Deployment in der letzten Woche erwähnen"

• "Fasse die Diskussion im Team-Chat von gestern zusammen"

• "Welche Dateien wurden diesen Monat im Projekt-Kanal geteilt?"

Vergleich mit chaindead/telegram-mcp

Schnellstart

Voraussetzungen

• Go 1.26+

• Ein Telegram-Konto

• API-Anmeldedaten von my.telegram.org (api_id und api_hash)

Installation

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

Vorkompilierte Binärdateien (macOS / Linux / Windows):

Download von GitHub Releases.

Go install:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

Aus dem Quellcode:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

Dies erstellt mcp-telegram (oder mcp-telegram.exe unter Windows) im aktuellen Verzeichnis.

Authentifizierung

Führen Sie den Auth-Befehl einmal aus, um eine Sitzungsdatei zu erstellen. Sie werden nach Ihrer Telefonnummer, dem Login-Code und (falls aktiviert) Ihrem 2FA-Passwort gefragt.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

Konfiguration

Erstellen Sie eine config.yaml:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

Umgebungsvariablen in ${...}-Syntax werden beim Laden erweitert.

Client-Konfiguration

Der Server kommuniziert über stdio – Ihr MCP-Client startet und verwaltet den Prozess.

Claude Code (CLI – über Befehl hinzufügen):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json oder claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (Einstellungen > MCP Servers > Hinzufügen):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

Konfiguration

ACL

Die ACL ist Default-Deny. Nur Chats, die explizit in acl.chats aufgeführt sind, sind zugänglich, und nur mit den von Ihnen angegebenen Berechtigungen.

Unterstützte Suchmuster:

Berechtigungstypen: read, send, draft, mark_read.

Wenn derselbe Peer auf mehrere Regeln zutrifft (z. B. über @username und user:ID), werden die Berechtigungen zusammengeführt – sie überschreiben sich nie gegenseitig.

Ratenbegrenzung

Der Abschnitt limits.rate konfiguriert einen globalen Token-Bucket, der alle Telegram-RPC-Aufrufe umschließt:

• requests_per_second – anhaltende Rate (Standard: 2.0)

• burst – maximale Burst-Größe (Standard: 3)

Medien-Download

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

Wenn konfiguriert, lädt tg_history Medien automatisch in das angegebene Verzeichnis herunter. Der Parameter download_to kann den Pfad überschreiben, jedoch nur innerhalb von media.directory oder dessen Unterverzeichnissen.

allowed_upload_dirs schränkt ein, aus welchen Verzeichnissen tg_send Dateien lesen darf. Der Dateiversand ist deaktiviert, sofern dies nicht konfiguriert ist.

Sicherheit

• Default-Deny ACL – kein Chat ist zugänglich, sofern er nicht explizit auf der Whitelist steht

• Dateisystem-Grenze – tg_send kann nur Dateien aus allowed_upload_dirs lesen; download_to ist auf Unterverzeichnisse von media.directory beschränkt

• Sitzungsdatei-Berechtigungen – erzwungen auf 0600 (nur Besitzer kann lesen/schreiben)

• Keine Protokollierung von Geheimnissen – API-Hashes, Sitzungs-Token und Auth-Keys werden niemals in Protokolle geschrieben

• Keine Offenlegung von Access-Hashes – interne Telegram-Access-Hashes werden aus allen Tool-Ausgaben entfernt

• Ratenbegrenzung – verhindert versehentlichen API-Missbrauch

• Lokale Zeitzone – Datumsfilter verwenden Ihre Systemzeitzone, nicht UTC

Lizenz

MIT

Wenn Sie dieses Projekt nützlich finden, geben Sie ihm bitte einen Stern – es hilft anderen, es zu entdecken.