telegram-bot-mcp

Ein MCP-Server, der es Claude ermöglicht, einen Telegram-Kanal über die Telegram Bot API zu verwalten – Abonnentenwachstum Tag für Tag verfolgen und Beiträge veröffentlichen, bearbeiten, anpinnen oder löschen.

🇮🇷 راهنمای فارسی · Bereitstellungsanleitung · راهنمای دپلوی

Was ist das?

Die Telegram Bot API ist eine einfache HTTPS-API. Dieses Repository kapselt sie im Model Context Protocol, sodass ein KI-Assistent sie als Werkzeuge aufrufen kann – „Wie hat sich der Kanal diese Woche entwickelt?“ statt curl https://api.telegram.org/bot.../getChatMemberCount.

Es wird in zwei Formen ausgeliefert, die auf denselben Werkzeugdefinitionen basieren:

Wähle den Remote-Server, wenn du tägliche Berichte möchtest, die ohne dich laufen. Wähle das Plugin, wenn du nur Claude Code nutzt und bevorzugst, dass nichts deinen Rechner verlässt.

Werkzeuge

Beide Varianten stellen dieselben acht Werkzeuge bereit.

Schnellstart (Remote-Server)

1. Erstelle einen Bot mit @BotFather → /newbot → kopiere den Token.

2. Füge den Bot als Administrator deines Kanals hinzu.

3. Erstelle ein HTTP-val auf val.town und füge remote/telegram-mcp.ts ein.

4. Setze drei Umgebungsvariablen in der Seitenleiste des Vals: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.

5. In Claude: Einstellungen → Connectors → Custom Connector hinzufügen → https://<your-val>.web.val.run/mcp → gib dein Passwort ein.

Eine vollständige Anleitung, einschließlich des lokalen Plugin-Pfads und der Fehlerbehebung: docs/deployment.md.

Sicherheit

In diesem Repository sind keine Anmeldeinformationen eingecheckt. config.json und .env sind gitignoriert; nur .example-Dateien werden versioniert. Bevor du einen Fork pushst, prüfe mit git status, dass keiner von beiden auftaucht.

Der Remote-Server implementiert einen vollständigen OAuth-2.1-Autorisierungsablauf, anstatt offen im Internet zu liegen:

• Anfragen ohne gültiges Bearer-Token erhalten 401 mit einem WWW-Authenticate-Header, der auf die Ressourcen-Metadaten verweist, gemäß RFC 9728.

• Clients registrieren sich dynamisch (RFC 7591); es müssen keine Client-Secrets verteilt werden.

• Autorisierungscodes werden mit PKCE (S256) geschützt, und Redirect-URIs werden gegen die registrierte Menge validiert.

• Access- und Refresh-Tokens sind HMAC-SHA256-signiert und zustandslos – 24 Stunden Access, 30 Tage Refresh.

• Der Zustimmungsbildschirm ist durch MCP_PASSWORD geschützt, das du selbst wählst.

Dein Bot-Token bleibt in den Umgebungsvariablen des Hosts und wird von keinem Werkzeug zurückgegeben.

Behandle MCP_PASSWORD wie ein Passwort für deinen Kanal. Jeder, der es hat, kann sich verbinden und Beiträge veröffentlichen.

Einschränkungen

Die Bot API meldet nur Abonnentenzahlen. Beitragsaufrufe, Weiterleitungen, Reichweite und die offiziellen Kanalstatistik-Diagramme von Telegram sind für Bots nicht verfügbar – diese erfordern einen MTProto-Client, der mit einem Benutzerkonto angemeldet ist, das den Kanal verwaltet.

Ein Bot kann im Allgemeinen nur Nachrichten bearbeiten, die er selbst gesendet hat. Telegram definiert ein Administratorrecht can_edit_messages („Nachrichten anderer Benutzer bearbeiten; nur für Kanäle“), aber das Verhalten von Bots gegenüber Beiträgen, die von menschlichen Administratoren veröffentlicht wurden, ist nicht klar dokumentiert – teste es an deinem eigenen Kanal, bevor du dich darauf verlässt. Beim Löschen sieht es anders aus: can_delete_messages deckt ausdrücklich Nachrichten anderer Benutzer ab.

Der Wachstumsvergleich erfordert, dass der Verlaufsspeicher zwischen den Ausführungen erhalten bleibt. Bei Val Town ist das der Blob-Speicher, und er bleibt erhalten. Beim lokalen Plugin ist es eine CSV-Datei – bewahre sie an einem dauerhaften Ort auf, nicht in einem temporären Verzeichnis.

Repository-Struktur

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

Tests

npm test

Erfordert Node 22.6+. Zweiundzwanzig Prüfungen decken den OAuth-Ablauf ab (401-Herausforderung, Discovery-Dokumente, dynamische Registrierung, PKCE-Ablehnung, Token- und Refresh-Grants, Ablehnung gefälschter Token) und das MCP-Protokoll (initialize, Benachrichtigungen, Werkzeugliste, Wachstums-Delta-Arithmetik, Werkzeug-Fehlerpfade). Die Telegram-API ist simuliert; es sind weder Netzwerkzugriff noch ein echtes Bot-Token erforderlich.

Die Testsuite läuft gegen die bereitgestellte Quelle selbst – tests/build.mjs schreibt genau eine Zeile um, den Val-Town-Blob-Import, und ändert nichts anderes.

Lizenz

MIT