tgread

Ein schreibgeschützter Telegram-MCP-Server. Erlaubt Claude Code, deine Kanäle, Gruppen und DMs zu lesen – und gibt ihm keine Möglichkeit, in sie zu schreiben.

./install.sh          # pinned venv + ~/.local/bin/tgread + MCP registration
tgread login          # api_id/api_hash, phone, code, 2FA
tgread status         # who am I, is the session live, are perms sane

Warum nicht einer der bestehenden Server

Es gibt gute Community-Server – chigwell/telegram-mcp hat 1,5k Sterne, 30 Mitwirkende und echte Release-Hygiene. Der Grund, dieses hier zu schreiben, ist kein Misstrauen gegenüber diesem Code. Es ist, dass der ehrliche Gewinn beim Selbstschreiben in Werkzeugoberfläche und Überprüfbarkeit liegt, nicht in der Anzahl der Abhängigkeiten – und das sind die beiden Dinge, die zählen, wenn der Prozess eine Telegram-Sitzung hält und einen Agenten mit angreiferkontrolliertem Text füttert.

MTProto von Hand zu schreiben wäre leichtsinnig – Telethon ist die Kryptografie, die DC-Migration und die Wiederverbindungslogik. Also bleibt es. Alles darüber gehört uns.

Related MCP server: telegram-mcp-server

Das Bedrohungsmodell

Kanäle zu lesen bedeutet, dass von einem Angreifer gewählter Text in einen Agenten gelangt, der eine Shell hält – und normalerweise auch alles andere, was du verbunden hast: E-Mail, Notizen, Cloud-Zugangsdaten. Das ist das dominierende Risiko hier, und es wird nicht dadurch behoben, wer den Server geschrieben hat. Einen Server ohne Schreiboberfläche zu wählen, ist eine der wenigen Abschwächungen, die nicht davon abhängt, dass sich das Modell gut verhält.

flowchart TD
    A["hostile channel post<br/>'ignore previous instructions…'"] --> B["tgread read_chat"]
    B --> C["UNTRUSTED envelope<br/>wrapped around every payload"]
    C --> D["agent context"]
    D --> E{"agent tries to act on it"}
    E -->|"send / delete / join"| F["no such tool exists<br/>tools/call → isError"]
    E -->|"raw TL request"| G["guard at _call → WriteBlocked"]
    E -->|"summarise for the user"| H["fine — this is the intended path"]
    style F fill:#1f6f43,color:#fff
    style G fill:#1f6f43,color:#fff

Drei Ebenen, in aufsteigender Reihenfolge danach, wie viel sie einem Bug standhalten würden:

1. Kein Schreibwerkzeug wird angekündigt. Eine injizierte Anweisung hat nichts, das sie aufrufen kann.

2. Jede Nutzlast wird mit einem UNTRUSTED CONTENT-Banner umhüllt, der sie als Daten kennzeichnet, nicht als Anweisungen – einschließlich Chat-Titel und Bios, die ebenfalls angreiferkontrolliert sind.

3. Die Transport-Sicherung. Telethon schleust jede ausgehende TL-Anfrage durch TelegramClient._call (68 interne Aufrufstellen erreichen sie über await self(req), und __call__ ist ein einzeiliger Delegat). ReadOnlyClient überschreibt sie. Ein Bug in dieser Datei kann das Konto weiterhin nicht verändern.

Die Sicherung fällt geschlossen aus: Eine Anfrage wird abgelehnt, es sei denn, ihr TL-Klassenname beginnt mit Get/Search/Resolve/Check/Find oder sie steht auf einer aus neun Einträgen bestehenden Infrastruktur-Allowlist. Drei lese-artige Anfragen werden namentlich verweigert, weil sie Effekte haben, die andere beobachten können – GetMessagesViews (erhöht den öffentlichen Aufrufzähler), GetBotCallbackAnswer (drückt einen Inline-Button), GetInlineBotResults (fragt einen Bot in deinem Namen ab). Verschachtelte Anfragen werden durchlaufen, sodass ein Schreibzugriff nicht in einem erlaubten InvokeWithLayer-Wrapper mitreisen kann.

flowchart LR
    R["TL request"] --> W["walk nested .query"]
    W --> D{"in EXPLICIT_DENY?"}
    D -->|yes| X["WriteBlocked"]
    D -->|no| I{"in INFRA_ALLOW?"}
    I -->|yes| P["to the wire"]
    I -->|no| V{"starts with Get/Search/<br/>Resolve/Check/Find?"}
    V -->|yes| P
    V -->|"no — incl. every<br/>name we've never seen"| X
    style X fill:#8b2020,color:#fff
    style P fill:#1f6f43,color:#fff

tgread check führt das offline aus: 26 Schreibanfragen blockiert, 17 Lesezugriffe erlaubt, unbekannte Namen fallen geschlossen aus, Verschachtelung geprüft. Kein Netzwerk, keine Sitzung, keine Zugangsdaten.

Werkzeuge

Es gibt bewusst keinen Mediendownload: Anhänge abzurufen bedeutet, vom Angreifer gewählte Bytes in das Dateisystem des Agenten zu schreiben. Die Metadaten von Nachrichten melden nur den Medien-Typ.

Betriebshinweise

• Verwende ein Zweitkonto. Userbots (jeder MTProto-Client, der nicht die offizielle App ist) können laut ToS gebannt werden. Dieses Risiko ist für jeden Server hier identisch.

• Die Sitzungsdatei ist ein Bearer-Token für das gesamte Konto. Das Ändern deines Telegram-Passworts macht es nicht ungültig. Nur tgread logout – das serverseitig widerruft, bevor es lokal löscht – oder Einstellungen → Geräte tut das. Behandle es wie einen privaten SSH-Schlüssel.

• pip install telegram-mcp ist weder dieses Projekt noch das von chigwell. Dieser PyPI-Name gehört zu einem nicht verwandten Projekt; die Übergabe von TELEGRAM_API_ID / TELEGRAM_API_HASH an dieses Projekt würde deine Zugangsdaten an Code Dritter weiterreichen. Absichtlich wird von hier nichts auf PyPI veröffentlicht.

• Der Zustand liegt in einem einzigen Verzeichnis – $TGREAD_STATE_DIR, Standard ~/.local/state/tgread, Modus 0700, das config.env (0600) und tgread.session (0600) enthält. Ein Verzeichnis zum chmoden, zum Sichern, zum Zerstören. tgread status weist darauf hin, wenn die Berechtigungen abweichen.

• install.sh verwendet uv sync --frozen – es installiert genau die Versionen aus der eingecheckten uv.lock und schlägt fehl, anstatt neu aufzulösen. Ein Resolver, der stillschweigend eine frische Upstream-Veröffentlichung aufgreift, ist der Weg, auf dem ein kompromittiertes Paket einen Prozess erreicht, der deine Sitzung hält.

Aufbau

Befehle

tgread login      interactive: API credentials, phone, login code, 2FA
tgread status     who am I, is the session valid, are permissions sane
tgread logout     revoke server-side, then delete locally
tgread check      offline self-test of the read-only guard
tgread serve      speak MCP over stdio — what Claude Code runs

login und logout verwenden einen einfachen Client, nicht den gesicherten: Die Sicherung dient dazu, den Agenten einzuschränken, nicht den Menschen am Terminal, der die Sitzung einrichtet oder widerruft. Alles, was der MCP-Server anfasst, läuft über ReadOnlyClient.