Telegram MCP — lokaler Read-only-Zugriff für KI-Agenten

Der lokale MCP-Server bietet Codex, Claude und anderen MCP-Clients drei Werkzeuge:

Der Server arbeitet nur lesend. Im Code gibt es keine Werkzeuge zum Senden, Bearbeiten oder Löschen von Nachrichten. Der Server wird lokal über STDIO gestartet und bietet bewusst keinen Netzwerk-HTTP/SSE-Zugriff.

Unterstützte Clients

• ChatGPT/Codex Desktop;

• Codex CLI und IDE-Erweiterung;

• Claude Code;

• Claude Desktop;

• jeder lokale MCP-Client mit STDIO-Unterstützung.

Der lokale Server funktioniert nicht direkt in chatgpt.com, claude.ai, auf dem Telefon oder auf einem anderen Computer: Diese Umgebungen können keinen Prozess auf Ihrer Maschine starten.

Related MCP server: tdl-mcp

Was Sie benötigen

• Windows 10/11, macOS oder Linux;

• Git;

• Python 3.10+;

• mindestens einen unterstützten MCP-Client.

Installation für Einsteiger

1. Terminal öffnen

• macOS: Command + Space → Terminal eingeben → Enter.

• Windows: Startmenü → PowerShell eingeben → PowerShell öffnen.

• Linux: Ctrl + Alt + T drücken oder die Terminal-Anwendung öffnen.

2. Projekt herunterladen

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

Wenn GitHub meldet, dass das Repository nicht gefunden wurde, hat Ihr Konto derzeit keinen Zugriff auf das private Repository.

3. Telegram API ID und API Hash erhalten

1. Öffnen Sie my.telegram.org.

2. Melden Sie sich mit Ihrer Telefonnummer an.

3. Öffnen Sie API development tools.

4. Erstellen Sie eine Anwendung, z. B. Local Telegram MCP.

5. Speichern Sie api_id und api_hash.

Senden Sie api_hash, den Anmeldecode oder das Cloud-Passwort nicht in einen Chat mit einer KI.

Erstellen Sie eine lokale .env.

macOS/Linux:

cp .env.example .env
nano .env

Speichern in Nano: Ctrl + O → Enter → Ctrl + X.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

Füllen Sie die Datei lokal aus:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. Abhängigkeiten installieren und bei Telegram anmelden

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

Das Skript findet selbst Python 3.10+, erstellt .venv, installiert Abhängigkeiten und fragt nach Telefonnummer, Code aus Telegram und, falls aktiviert, Cloud-Passwort. Geben Sie diese nur in Ihrem eigenen Terminal ein.

Verbindung zum Agenten herstellen

Verwenden Sie in allen Beispielen absolute Pfade, die das Setup-Skript ausgibt. Der Befehl ist Python innerhalb von .venv, das Argument ist telegram_mcp_server.py.

Codex CLI und ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

In ChatGPT/Codex Desktop können Sie auch Settings → MCP servers → Add server öffnen, STDIO auswählen und dieselben Command und Arguments angeben. Nach dem Speichern klicken Sie auf Restart. Lokale Clients desselben Codex-Hosts verwenden die Konfiguration ~/.codex/config.toml gemeinsam.

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

Starten Sie eine neue Claude-Code-Sitzung und geben Sie /mcp ein. Der Bereich user macht den Server in verschiedenen lokalen Projekten dieses Benutzers verfügbar.

Claude Desktop

Öffnen Sie die Developer/MCP-Einstellungen und fügen Sie einen lokalen STDIO-Server hinzu. Wenn Ihre Version von Claude Desktop eine JSON-Konfiguration verwendet, fügen Sie das Objekt hinzu und behalten die übrigen Server bei:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

Typische Speicherorte der Datei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

• Windows: %APPDATA%\Claude\claude_desktop_config.json.

Starten Sie Claude Desktop vollständig neu und öffnen Sie einen neuen Chat.

Anderer STDIO-MCP-Client

Verwenden Sie eine entsprechende Konfiguration:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

Abschließende Prüfung

Bitten Sie den Agenten:

Verwende Telegram list_chats mit limit=10 und zeige Name, Typ und Anzahl der ungelesenen Nachrichten.

Betrachten Sie die Installation erst als abgeschlossen, wenn der Agent tatsächlich eine Liste Ihrer Chats zurückgegeben hat.

Mehrere Konten

Der Server unterstützt separate lokale Sitzungen default, work, personal und andere. Die Anleitung finden Sie in docs/MULTI_ACCOUNT.md.

Anleitung für KI-Agenten

Wenn die Installation von Codex, Claude oder einem anderen Agenten durchgeführt wird, bitten Sie ihn, die docs/AGENT_SETUP.md vollständig zu lesen und Schritt für Schritt zu befolgen. In dieser Datei sind Sicherheitsregeln und Verzweigungen für verschiedene Betriebssysteme festgehalten.

Sicherheit und Einschränkungen

• .env und sessions/ sind von Git ausgeschlossen;

• die Datei .session gewährt Zugriff auf das Konto – kopieren oder veröffentlichen Sie sie nicht;

• Mediendateien werden nicht heruntergeladen, es wird nur das Merkmal has_media zurückgegeben;

• Anfragen an Telegram werden in Ihrem Kontonamen ausgeführt und unterliegen den Telegram-Limits;

• führen Sie nicht zwei Operationen mit derselben .session gleichzeitig aus;

• stellen Sie diesen Server nicht ins Internet.

Weitere Details: SECURITY.md.

Wenn etwas nicht funktioniert

Siehe docs/TROUBLESHOOTING.md.

Entwicklung

.venv/bin/python -m unittest discover -s tests -v

Projektstruktur:

Lizenz

MIT – Das Projekt kann verwendet, geändert und verbreitet werden, sofern der Urheberrechtshinweis und der Lizenztext erhalten bleiben.