telegram-mcp

Reicht Claude das neueste Bild aus einer Telegram-Gruppe.

Die Screenshots werden von einem Bot gepostet, und die Telegram Bot API gibt niemals die eigenen Nachrichten eines Bots zurück – daher liest dieses Tool die Gruppe mit einem BenutzerKonto über MTProto (Telethon). Das ist der einzige Weg, diese Fotos zu sehen.

Einrichtung (einmalig)

1. Holen Sie sich eine API-ID und einen Hash von https://my.telegram.org → API-Entwicklungstools.

2. cp .env.example .env und füllen Sie TELEGRAM_API_ID, TELEGRAM_API_HASH und TELEGRAM_CHAT_ID aus (die numerische ID der Gruppe, negativ).

3. Erstellen Sie die Umgebung:

python -m venv .venv
.venv\Scripts\pip install -e .[dev]

4. Melden Sie sich an – in einem Terminal, nicht über Claude:

.venv\Scripts\telegram-mcp-login

Es fragt nach Ihrer Telefonnummer, dem Code, den Telegram sendet, und Ihrem Zwei-Faktor-Passwort, falls Sie eines haben, und schreibt dann session/telegram.session.

Es listet auch einmal Ihre Dialoge auf und gibt Ihnen den Namen der Gruppe aus. Die Auflistung ermöglicht es der Sitzung, später eine Supergruppe aufzulösen – Telegram verwandelt eine Gruppe in eine solche, sobald ein Bot beitritt – und der Name ist Ihre Bestätigung, dass TELEGRAM_CHAT_ID dorthin zeigt, wo Sie es vermuten. Wenn es die Gruppe nicht finden kann, sagt es das und beendet sich mit einem Exit-Code ungleich Null.

Related MCP server: telegram-user-mcp

Installation in Claude

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

Benutzerbereich, sodass jedes Projekt es erhält.

Werkzeuge

• get_latest_image() – das neueste Foto in der Gruppe, das die letzten 200 Nachrichten durchsucht.

• wait_for_next_image(timeout_seconds=120) – blockiert, bis ein Foto ankommt, das neuer ist als der Zeitpunkt des Aufrufs. Warten kostet keine Tokens; der Prozess wartet auf einem Socket. Auf 1–240 s begrenzt, um innerhalb des Tool-Timeout des MCP-Clients zu bleiben.

Beide geben das Bild (JPEG, lange Kante ≤1568 px) plus eine Textzeile zurück: zuerst den Pfad zum unveränderten Original, dann die Nachrichten-ID, den Zeitstempel, den Absender und die Bildunterschrift, in Anführungszeichen. Beschneiden Sie das Original, wenn die Verkleinerung feine Details verliert.

Nur ein Prozess kann die Sitzung gleichzeitig halten. Eine zweite Claude Code-Sitzung, die ein Tool aufruft, während die erste mitten im Aufruf ist, wird gebeten, es in einem Moment erneut zu versuchen, anstatt einen SQLite-Fehler zu erhalten.

Tests

.venv\Scripts\python -m pytest

Kein Netzwerk, kein Telegram-Konto erforderlich – Telethon wird durchgehend simuliert.

Sicherheit

session/telegram.session ist ein vollständiger Login zu Ihrem Telegram-Konto. Es ist gitignored und verlässt diesen Rechner nie. Jeder, der diese Datei besitzt, kann Ihre Nachrichten lesen; löschen Sie sie und führen Sie den Login erneut aus, wenn Sie vermuten, dass sie kopiert wurde. Anmeldedaten befinden sich nur in .env – niemals in Dokumenten, Prompts oder Tickets.