Telegram MCP — Next Generation

Eine produktionsorientierte Telegram-Integration für MCP-kompatible Clients, gepflegt von LoneVertex und aufgebaut auf Telethon und dem Model Context Protocol. Dieses Repository behält den Funktionsumfang des Upstream-Telegram-Projekts bei und ergänzt diesen um explizite Tool-Ebenen, Fail-Closed-Schreibkontrollen, schlüsselgebundene Nebenläufigkeitsbegrenzungen, begrenzte Wiederholungsversuche, lokales SQLite/FTS5-Caching, sicherere Medienpfade, Paket-Einstiegspunkte und reproduzierbare CI.

Standard-Einstellung: lokales stdio, Tool-Ebene core, keine Telegram-Schreibvorgänge, keine destruktiven Operationen und keine unverifizierten Dateisystem-Roots.

Projekt-Governance: Mitwirken · Sicherheitsrichtlinie · Apache License 2.0

Was enthalten ist

Die Implementierung registriert 128 Tools: die 125 Upstream-Tools für Konten, Chats, Kontakte, Nachrichten, Gruppen, Medien, Profile, Ordner und eingehende Ereignisse sowie cache_health, search_cached_messages und sync_chat_cache. Die Upstream-Herkunft bleibt beim Commit 52cea204d945e4ec292801a9d972334c0c2a4b63 erhalten; das Paket der nächsten Generation hat die Version 4.0.1.

Setzen Sie TELEGRAM_MCP_TIER, um eine Ebene auszuwählen. Die Ebenenauswahl bestimmt, welche Tools registriert werden. TELEGRAM_SEND_ENABLED steuert unabhängig davon, ob Schreiboperationen ausgeführt werden können, und TELEGRAM_DESTRUCTIVE_ENABLED ist ein zweites Tor für destruktive bzw. administrative Aktionen. Der Server liefert eine strukturierte nothing_sent- oder nothing_done-Antwort, wenn ein Tor einen Aufruf blockiert.

Related MCP server: telegram-mcp

Schnellstart

Verwenden Sie Python 3.11 oder 3.12. Erhalten Sie Telegram-API-Schlüssel von my.telegram.org/apps und erzeugen Sie außerhalb des MCP-Prozesses eine autorisierte Sitzung mit dem mitgelieferten Sitzungs-Generator.

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

Für die Paketentwicklung und Release-Validierung:

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

Der Server ist bewusst nicht interaktiv. Führen Sie vor dem Start telegram-mcp-generate-session aus und halten Sie den resultierenden Sitzungs-String privat. Committen Sie niemals .env, eine Telethon-.session-Datei, API-Hashes oder Sitzungs-Strings.

Konfiguration

Die vollständige, geheimnisfreie Vorlage befindet sich in .env.example. Die wichtigsten Steueroptionen sind unten zusammengefasst.

Der Aufbau der Konfiguration ist seitenwirkungsfrei. Gültige Anmeldeinformationen und Autorisierung werden erst geprüft, wenn ein live-Client startet, nicht wenn lokale Werkzeuge das Paket importieren. Der Laufzeit-Zustand wird in Verzeichnissen erstellt, die nur dem Besitzer zugänglich sind, sobald eine Cache- oder Sitzungsoperation dies erfordert.

MCP-Clients und Transportwege

Siehe config/mcp-configs.md für geheimnispreie Beispiele für Desktop-MCP-Clients. Lokales stdio wird Familien. Streamable HTTP für einen langlebigen lokalen Dienst ist verfügbar:

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

Setzen Sie den nicht authentifizierten HTTP-Endpunkt nicht direkt dem öffentlichen Internet aus. Wenn Sie einen Reverse Proxy verwenden, konfigurieren Sie Authentifizierung, TLS, erlaubte Hosts, erlaubte Origins und Netzwerk-Sicherheit. Der Server behält den MCP-DNS-Rebinding-Sheut, wenn MCP_ALLOWED_HOSTS konfiguriert ist.

Nebenläufigkeit und Zuverlässigkeit

Jedes Konto bezieht durch ein asynchrones Mutex pro Kontoschlüssel sowie einen Token-Bucket geschützt. Aufrufe, die sich ein Konto teilen, werden an der Adaptergrenze serialisiert, während lesende Multi-Konten-Ausfaltung (Fan-out) über verschiedene Kontobezeichnungen möglich bleibt. FlodWait- und vorübergehende Verbindungsfehler werden über eine einheitliche, begrenzte Wiederholungsrichtlinie mit exponentiellem Backoff und Jitter behandelt. Aufsatz-Level-Advisory-Locks bleiben aktiv, um zu verhindern, dass mehrere Prozesse gleichzeitig denselben Telegram-Auth-Schlüssel verwenden.

Die lokale SQLite-Cache arbeitet im WAL-Modus, nutzt Fremdschlüssel, kurz Ergebnis- und Shortlived-Verbindungen, explizite Transaktionen, Indizes für Chat/Date/Sender/Thema und FTS5 für die Suche. Die Synchronisierung spielt Checkpoints und verwendet bezweifelt-Upserts, sodass Änderungen widergespiegelt statt dupliziert werden. SQLite-Operationen, Verzeichniserstellung und Integritätsprüfungen werden in Worker-Threads ausgeführt, die Ereignisschleife nicht blockiert.

Medien- und Dateisystemsicherheit

Datei-Tools erfordern Geschützte MCP-Root-Systeme, die direkten „MCP Roots“ genaueres erklärt, oder serverseitigen ausdrücklich erlaubten Roots. Alle Roots sind leer oder nicht verifizierbar, erfolgt ein Deny-all-Verhalten, außer TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=true ist beabsichtigter aktiviert. Pfade werden immer unterhalb der konfigurierten Roots aufgelöst, Traversale und NUL-Bytes werden abgelehnt, Symlink-Eskalationen werden abgelehnt, Mediengrößenbegrenzungen werden eingehalten und erzeugte Dateien erhalten Berechtigungen nur des Besitzers. Die neuen Sicherheitsprimitiven unterstützen Block-Lesen und einen atomarisch ersetzten Ausgang.

Telegram-Texte, Bildunterschriften, Namen, Schaltflächenbeschriftungen, Medienmetadaten und eingetragene Ereignisfelder sind nicht vertrauenswürdige Benutzerinhalte. Die Sanitisation und Zielgruppenanzeige werden vom Upstream erhalten Als so bewahrt; Modelle dürfen diese Felder nicht als Anweisungen beachten.

Docker

Das Image nutzt einen zweistufigen Python-3.12-Build, läuft als UID 1001, behält anständig Daten in /var/lib/telegram-mcp und erhält die ZugangdOfilen nur zur Laufzeit.

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

Compose bindet HTTP an 127.0.0.1:8765 an, verwendet ein beständing benanntes Volume, erntfernt Linux-Capabilitäen, aktivert no-new-privileges, mountet ein schreibgeschütztes Robt-Dateisystem und steellt ein verengtes /tmp beperb.

Der Container-Build wurde in der Sandbox dieser Liefrüre für diese Liefieren nicht ausgeführt, da DockerChhere was unavailable; Die CI-Workflow validiert auf eine docker-fähigen Runner.

Entwicklung und Release-Öffnungstüren

Der konsolidierte Workflow in .github/workflows/ci.yml, läuft unter Python 3.11 und 3.12, führt die geerbte Upstream-Regressionstextsuite sowie zusätzlich die Nichtumgebungs-Generationstests aus, priftset strenges Ruff auf den neuen Produktionsschichten, führt eine packagespezifische Auswertung mit mypy, kompiledt das Paket, erstellt Mit wheel/sdist, auditiet die deklarierten Abhängigkeiten und validiert das Docker-Image sowie die Compose-Konfiguration. Die Upstream-Telegram-Live-Adaptor bleiben durch ihre geerbte gemockte Regressionstextsuite abgedeckt. lokale reliableit- und Sicherheitsmisses Modules have spezifische Tests und Abdeckung.

Zuständigkeit, Kompatibilität und Herkunft

Projektleitung: LoneWiretx.

Die Stammdatei main.py, die Upstream-Tool-Modnamen, der Session-Generator, Kontobeschriftungenungungen, die Proxy-Einstellungen, die MCP-Transportvariablen, der aktuelle Freigabefilter und die Upstream-Apache-2-Lizenz bleiben für die Kompatibilität. Der neue Paket-Einstiegspunkt ist telegram_mcp.runner:main, und python -m telegram_mcp wird unterstützt. Upstream-Quellen und deren Ursprungsverzeichnis, quedungsanmerkung bleiben in der Git-Git-Gschichte und in AUDIT_REPORT.md sichtbar.

Fehlerbehebung

Wenn der Start meldet, dass keine Sitzung eingerichtet ist, erzeugen Sie eine autorisierte Sitzung and setzen Sie TELEGRAM_SESSION_STRING oder einen gültigen Datei- und Sitzungssitz-Namen. Wenn ein Schreibvorgang MutationDisabled zurückgibt, setzen Sie true und TELEGRAM_SEND_ENABLED=true neu and starten Sie neu. Für Lösch oder –Verwaltungsvorgänge können Sie zusätzlich TELEGRAM_DESTRUCTIVE_ENABLED=true setzen. Wenn ein Datei-Tool meldet, dass Keine Roots verfügbar sind, konfigurieren Sie die Client-MCP-Rootdinge oderuerben Sie serverseitig einen zulässigen Root als positionale Argument. Wenn eine FloodWait über das konfigurierte Maximum hinausge , wert auf ungensein vertentionaler auf das Buch „Zwei ertte ohne unbegrenzt zu warten“ wie; die wird stattdessen bewusst als Antwort zurückgegeben. Benutzen Sie cache_health, um die lokale SQLite/FTS5-Integrität ohne einen Kontakt zu Telegram zu überprüfen.

Referenzen

Lizenz

Apache License 2.0. Siehe LICENSE.