telegram-mcp-server

MCP-Server für Telegram über einen User-Account (MTProto/Telethon). Liest Chats/Nachrichten/Medien und sendet Nachrichten/Dateien. Läuft lokal über stdio.

Warum User-Account statt Bot?

Ein Bot kann keine Gruppen-Historie und keine vor seinem Beitritt geposteten Medien lesen (und hat ein 20-MB-Download-Limit). Für „hol mir die Bilder aus der Gruppe" braucht es einen User-Client. Session-Datei = voller Account-Zugriff → lokal halten, chmod 600, nie committen.

Related MCP server: Telegram MCP Server

Setup

1. API-Credentials auf https://my.telegram.org (API development tools) erzeugen.

2. Repo installieren (venv + editierbar; Python ≥3.10):

   python3 -m venv .venv
   .venv/bin/pip install -e .

3. Environment setzen:

   export TELEGRAM_API_ID=...
   export TELEGRAM_API_HASH=...
   export TELEGRAM_PHONE=+49...        # nur für den Login nötig
   # optional:
   export TELEGRAM_SESSION="$HOME/.telegram-mcp/telegram.session"
   export TELEGRAM_DOWNLOAD_DIR="$HOME/Downloads/telegram-mcp"

4. Einmalig einloggen (erzeugt die Session-Datei, fragt Code + ggf. 2FA):

   .venv/bin/python -m telegram_mcp_server.login

In Claude Code registrieren

claude mcp add telegram \
  -e TELEGRAM_API_ID=... \
  -e TELEGRAM_API_HASH=... \
  -e TELEGRAM_SESSION="$HOME/.telegram-mcp/telegram.session" \
  -- /ABSOLUTER/PFAD/telegram-mcp-server/.venv/bin/telegram-mcp-server

Die -e-Flags sind nötig, weil ein von Claude Code gestarteter MCP-Server die Shell-exports aus dem Setup NICHT erbt. Alternativ die env-Sektion in der MCP-Konfiguration nutzen. TELEGRAM_DOWNLOAD_DIR optional per weiterem -e setzen. Nach dem Registrieren eine neue Claude-Code-Session starten, damit der Server erscheint.

Tools

chat akzeptiert Chat-id, @username oder (Teil-)Titel; bei mehrdeutigem Titel kommt ein Fehler mit den Treffern statt einer Rate-Auflösung.

get_messages/search_messages liefern pro Nachricht auch chat_id mit — Treffer aus der globalen Suche sind damit direkt in weiteren Tool-Aufrufen (z.B. download_media) verwendbar.

Mehrere gleichzeitige Sessions

Jeder MCP-Client startet einen eigenen Serverprozess. Alle zeigen auf dieselbe Session-Datei, und Telethon legt darin veraenderlichen Zustand ab — vor allem update_state. SQLiteSession.set_update_state schreibt mit insert or replace, also ein blindes Ueberschreiben ohne Vergleich.

Gemessen am 14.09.2026 an einer Kopie einer echten Session: Zwei Schreiber verwerfen gegenseitig ihren Stand — 4997 Update-Positionen still verloren, kein Fehler. Dazu nutzt die Datei journal_mode=delete (kein WAL), ein Schreiber sperrt also die ganze Datei; ein konkurrierender Schreibvorgang scheitert nach dem 5-s-Standardtimeout mit database is locked.

Deshalb liest der Server aus einer prozesseigenen Kopie und schreibt nie zurueck (_private_session_copy). Kopiert wird ueber SQLites Backup-API, nicht per Dateikopie: Ein anderer Prozess kann mitten im Schreiben sein, und eine einfache Kopie kann eine halb geschriebene Seite erwischen.

Was das kostet: Der Entitaeten-Cache waechst nicht mehr ueber Prozesse hinweg, es gibt also etwas mehr Aufloese-Aufrufe. Fuer Lesen und Senden wird nur der auth_key gebraucht; update_state und der Cache sind Beschleuniger.

login.py ist davon nicht betroffen und schreibt weiterhin die echte Datei.

⚠️ Der naheliegende Fix receive_updates=False traegt nicht: Er schaltet nur den Zufluss ab. Der set_update_state-Aufruf in Telethons telegrambaseclient.py laeuft beim Disconnect und ist nicht von _no_updates geschuetzt — geschrieben wird trotzdem.

Entwicklung / Tests

python3 -m venv .venv && .venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest tests/ -v

Tests laufen ohne Live-Account (Client wird gemockt).

Smoke-Test (einmalig nach Login, mit echtem Account)

.venv/bin/python -m telegram_mcp_server.login        # 1) Session erzeugen
# 2) get_me / list_chats / get_messages / download_media manuell über den
#    MCP-Client (Claude Code) prüfen:
#    - get_me                         -> zeigt deinen Account
#    - list_chats query="<gruppe>"    -> findet eine deiner Gruppen
#    - get_messages chat=<id> limit=5 -> liefert Nachrichten
#    - search_messages query="..."    -> globale Suche (übt _search_global live aus;
#                                         Treffer müssen chat_id tragen)
#    - get_recent_media chat=<id> kind="photo" -> lädt Fotos nach $TELEGRAM_DOWNLOAD_DIR

Erster echter Integrationstest = ein Medienabruf aus einer deiner Gruppen. Die globale search_messages (ohne chat) ist der einzige Pfad, der _search_global/SearchGlobalRequest real ausführt — im Smoke-Test nicht überspringen.

Maintainer

Schimmi — https://schimmilab.de Issues und Pull Requests willkommen.