Telegram MCP Server

Ein lokaler Model Context Protocol-Server, der einem KI-Agenten (Claude Code, Claude Desktop oder einem beliebigen MCP-Client) kontrollierten Zugriff auf dein eigenes Telegram-Konto gibt: Chats auflisten, Verlauf lesen, suchen und Nachrichten senden – über die MTProto-API von Telegram.

Erstellt mit Python + Telethon. Läuft vollständig auf deinem Rechner; deine Anmeldesitzung verlässt ihn nie.

Warum

Telegrams Bot-API kann deine bestehenden Chats nicht sehen; ein Bot ist eine separate Identität und empfängt nur Nachrichten, die ihm explizit gesendet werden. Damit ein Agent mit deinen echten Unterhaltungen arbeiten kann, benötigst du die MTProto-Client-API, authentifiziert als dein Benutzerkonto. Dieses Projekt kapselt das in einem kleinen, fokussierten MCP-Server, sodass jeder MCP-fähige Agent dein Telegram lesen und darauf reagieren kann – ohne dass du jedes Mal Klebecode schreiben musst.

Related MCP server: telegram-mcp

Wie es zusammenpasst

Ein Telegram-Bot ist eine separate Identität und sieht nur Nachrichten, die an ihn gesendet werden. Damit ein Agent mit deinen Unterhaltungen arbeiten kann, authentifiziert sich der Server über MTProto als dein Benutzerkonto, weshalb die Session-Zeichenfolge so wichtig ist.

flowchart LR
    AGENT["<b>MCP client</b><br/>Claude Code · Claude Desktop<br/>or any MCP-capable agent"]

    subgraph LOCAL ["Your machine — nothing leaves it but Telegram traffic"]
        direction TB
        SRV["<b>server.py</b> · FastMCP stdio server<br/>connects lazily on first tool call<br/>verifies the session is authorized"]
        TOOLS["<b>6 tools</b><br/>get_me · list_chats · get_history<br/>search_messages · search_all · send_message"]
        ENV[("<b>.env</b> · git-ignored<br/>api_id · api_hash<br/><b>SESSION_STRING</b><br/><i>equivalent to being logged in as you</i>")]
        LOGIN["<b>login.py</b> · run once<br/>phone + code + 2FA → StringSession"]
        SRV --> TOOLS
        LOGIN -->|"writes"| ENV
        ENV -->|"reads"| SRV
    end

    subgraph TL ["Telethon → MTProto"]
        direction TB
        M1["iter_dialogs"]
        M2["iter_messages"]
        M3["SearchGlobalRequest"]
        M4["send_message"]
    end

    TG[("<b>Telegram</b><br/>your real account,<br/>your existing chats")]
    BOT(["Bot API<br/><i>cannot see your chats —<br/>this is why MTProto</i>"])

    AGENT <-->|"MCP over stdio"| SRV
    TOOLS --> M1
    TOOLS --> M2
    TOOLS --> M3
    TOOLS --> M4
    TL <--> TG
    BOT -.->|"✗"| TG

    classDef secret fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fee2e2
    classDef no fill:#0f172a,stroke:#475569,stroke-width:1.5px,color:#94a3b8
    classDef core fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e2e8f0
    class ENV secret
    class BOT no
    class SRV,TOOLS core

Die Ergebnisse kommen als einfache JSON-serialisierbare Dictionaries zurück, sodass der Agent aus strukturierten Daten zusammenfasst, anstatt aus gescraptem Text.

Funktionen

• 6 Tools für die gängigen Lese-/Schreibaktionen (siehe unten)

• Nur lokal – Anmeldedaten und Sitzung liegen in einer git-ignorierten .env; nichts wird außer an Telegram gesendet

• Standard-MCP-stdio-Server – funktioniert mit Claude Code, Claude Desktop oder jedem MCP-Client

• Einmalige Anmeldung – interaktives Skript speichert eine wiederverwendbare Session-Zeichenfolge; keine erneute Authentifizierung bei jedem Lauf

• Klein und lesbar – ~150 Zeilen Python, leicht zu prüfen und zu erweitern

Tools

chat akzeptiert einen Benutzernamen (@name), eine numerische ID, eine Telefonnummer, einen t.me-Link oder den Anzeigenamen des Chats.

Schnellstart

1. Installieren

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. API-Anmeldedaten abrufen

Gehe zu my.telegram.org → API-Entwicklungstools → erstelle eine App → kopiere api_id und api_hash.

3. Anmelden (einmalig)

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

Gib deine api_id/api_hash, Telefonnummer (mit Ländervorwahl) und den Anmeldecode ein, den Telegram dir sendet (plus dein 2FA-Passwort, falls festgelegt). Dies schreibt eine wiederverwendbare Sitzung in .env.

4. Bei deinem MCP-Client registrieren

Claude Code:

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop; füge zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

Starte deinen Client neu und die telegram-Tools sind verfügbar.

Beispiel

Du: Suche in allen meinen Telegram-Chats nach „Rechnung“ und fasse zusammen, was offen ist.

Der Agent ruft search_all("invoice") auf, was Folgendes zurückgibt:

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

…und der Agent fasst von dort aus zusammen.

So funktioniert es

login.py authentifiziert sich einmalig über Telethon und speichert eine StringSession in .env. server.py erstellt einen FastMCP-stdio-Server, verbindet sich lazy beim ersten Tool-Aufruf, überprüft, ob die Sitzung autorisiert ist, und ordnet jedes Tool einem Telethon-Aufruf zu (iter_dialogs, iter_messages, SearchGlobalRequest, send_message). Die Ergebnisse werden als einfache JSON-serialisierbare Dictionaries zurückgegeben.

Sicherheit

• Halte .env privat. Die SESSION_STRING entspricht einer Anmeldung als du. Sie ist git-ignoriert, committe sie niemals.

• Alles läuft lokal; der Server kommuniziert nur mit den Servern von Telegram.

• Die Automatisierung eines BenutzerKontos ist eine Grauzone in den Telegram-Nutzungsbedingungen. Das Lesen deines eigenen Kontos ist in der Regel in Ordnung; halte das Senden in menschlichem Tempo und vermeide Massen-/Spam-Aktivitäten, um Kontolimits zu vermeiden.

Einschränkungen

• Noch keine automatisierte Testsuite; manuell gegen ein Live-Konto verifiziert.

• search_messages durchsucht einen einzelnen Chat; verwende search_all für eine globale Suche.

• Die Auflösung des Anzeigenamens fällt auf das Scannen deiner Dialogliste zurück, daher sind exakte Benutzernamen/IDs schneller und zuverlässiger.

Lizenz

MIT