Telegram Notification MCP Server

Ein MCP-Server (Model Context Protocol), der Benachrichtigungen an Telegram sendet, wenn Claude Code Aufgaben abschließt. Entwickelt mit TypeScript unter Verwendung des Cloudflare Agents SDK und bereitstellbar auf Cloudflare Workers.

📢 Bevorzugen Sie Discord? Dann schauen Sie sich Discord Notification MCP für Discord-Benachrichtigungen an.

Funktionen

• 🤖 MCP-Tool: Stellt ein send_telegram_message-Tool zum Senden von Benachrichtigungen bereit

• 🚀 Cloudflare Workers: Läuft serverlos mit globaler Verteilung

• 🔐 Authentifiziert: Erfordert ein Bearer-Token, das als Cloudflare-Secret gespeichert ist

• 🌐 Streamable HTTP: Verwendet den aktuellen zustandslosen MCP-Transport

• 💬 Nachrichtenformatierung: Unterstützt Markdown- und HTML-Formatierung

• 📝 Formatierung: Unterstützt Markdown- und HTML-Nachrichtenformatierung

Related MCP server: claude-telegram-alerts

Architektur

Dieser Server implementiert die MCP-Spezifikation mithilfe des Cloudflare Agents SDK:

• POST /mcp: Zustandsloser Streamable-HTTP-Endpunkt für die MCP-Kommunikation

• GET /sse: Gibt 410 Gone zurück; Legacy-SSE-Clients müssen auf /mcp migrieren

• Entwickelt mit TypeScript, MCP SDK und Cloudflare Agents SDK

• Korrekte JSON-RPC-2.0-Fehlerbehandlung

• Node.js-Kompatibilitätsmodus aktiviert

Einrichtung

Voraussetzungen

1. Telegram-Bot: Erstellen Sie einen Bot über @BotFather und erhalten Sie Ihr Bot-Token

2. Chat-ID: Erhalten Sie Ihre Chat-ID, indem Sie Ihrem Bot eine Nachricht senden und Folgendes aufrufen:

   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

3. Cloudflare-Konto: Registrieren Sie sich unter cloudflare.com

Installation

1. Klonen Sie dieses Repository

2. Installieren Sie die Abhängigkeiten:

   pnpm install

Konfiguration

1. Erstellen Sie anhand des Beispiels eine .dev.vars-Datei:

   cp .dev.vars.example .dev.vars

   Bearbeiten Sie dann .dev.vars mit Ihrem Bot-Token und Ihrer Chat-ID. Diese Datei wird sowohl für die lokale Entwicklung als auch für die Bereitstellung verwendet.

2. Für die Produktionsbereitstellung generieren Sie ein MCP-Bearer-Token und richten Sie Cloudflare-Secrets ein:

   openssl rand -hex 32
   pnpm exec wrangler secret put BOT_TOKEN
   pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional
   pnpm exec wrangler secret put MCP_AUTH_TOKEN

   Hinweis: DEFAULT_CHAT_ID ist optional. Wenn sie nicht festgelegt ist, müssen Sie beim Aufruf des send_telegram_message-Tools einen chat_id-Parameter angeben.

3. Aktualisieren Sie bei Bedarf wrangler.toml mit dem Namen Ihres Workers

Bereitstellung

Bereitstellung auf Cloudflare Workers:

Bereitstellung mit Wrangler:

# First set secrets
pnpm exec wrangler secret put BOT_TOKEN
pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional

# Then deploy
pnpm run deploy

Alternative: Kontinuierliche Bereitstellung

Sie können die kontinuierliche Bereitstellung auch direkt über das Cloudflare-Dashboard einrichten. Weitere Informationen zur Git-Integration mit Cloudflare

Konfiguration von Claude Code

Fügen Sie den MCP-Server mithilfe von Streamable HTTP und demselben Bearer-Token zu Claude Code hinzu:

# For production deployment
claude mcp add --scope user --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify https://your-worker-name.workers.dev/mcp

# For local development
claude mcp add --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify http://localhost:8787/mcp

Das Token ist der Client-Zugriff auf den MCP-Endpunkt, nicht das Telegram-Bot-Token. Setzen Sie das Bot-Token niemals in die MCP-Konfiguration von Claude.

Sie können die Konfiguration wie folgt überprüfen:

claude mcp list

Verwendung

Nach der Konfiguration kann Claude Code Benachrichtigungen an Ihr Telegram senden, wann immer Sie sie benötigen.

Verfügbares Tool

send_telegram_message: Senden Sie eine Benachrichtigungsnachricht an Telegram

• text (erforderlich): Der zu sendende Nachrichtentext

• chat_id (optional): Telegram-Chat-ID (verwendet DEFAULT_CHAT_ID, falls nicht angegeben)

• parse_mode (optional): „Markdown" oder „HTML" für die Nachrichtenformatierung

• disable_notification (optional): Nachricht stumm senden

Beispielverwendung:

// Uses DEFAULT_CHAT_ID from environment
await send_telegram_message({ text: "Task completed!" })

// Send to specific chat (overrides DEFAULT_CHAT_ID)
await send_telegram_message({ text: "Hello!", chat_id: "123456789" })

// Send with Markdown formatting
await send_telegram_message({ 
  text: "*Bold* and _italic_ text", 
  parse_mode: "Markdown" 
})

Wann Sie Benachrichtigungen erhalten

Claude Code sendet Benachrichtigungen, wenn:

• Sie explizit darum bitten: „benachrichtige mich, wenn fertig" oder „lass es mich auf Telegram wissen"

• Fehler während der Ausführung auftreten

• Wichtige Meilensteine erreicht werden

• Eine Benutzereingabe oder ein Eingriff erforderlich ist

Beispielszenarien

# You say: "Deploy to production and notify me when done"
# Result: 🤖 Claude Code Notification
#         Deployment completed successfully! The app is now live.

# You say: "Run all tests and let me know the results"
# Result: 🤖 Claude Code Notification
#         All tests passed! 52/52 tests successful.

# You say: "Process this data and notify me if there are any errors"
# Result: 🤖 Claude Code Notification
#         Error: Failed to process row 451 - invalid date format

Beispiel-Benachrichtigungen

CLAUDE.md-Beispiele

Um Claude Code zu ermutigen, Telegram-Benachrichtigungen effektiv zu nutzen, fügen Sie diese zu Ihrer CLAUDE.md hinzu:

# Telegram Notifications

Use the mcp__telegram-notify__send_telegram_message tool to send notifications to Telegram.

- Always send a Telegram notification when:
  - A task is fully complete
  - You need user input to continue
  - An error occurs that requires user attention
  - The user explicitly asks for a notification (e.g., "notify me", "send me a message", "let me know")

- Include relevant details in notifications:
  - For builds/tests: success/failure status and counts
  - For errors: the specific error message and file location

- Use concise, informative messages like:
  - "✅ Build completed successfully (2m 34s)"
  - "❌ Tests failed: 3/52 failing in auth.test.ts"
  - "⚠️ Need permission to modify /etc/hosts"

Entwicklung

Lokal ausführen:

# Start local development server
pnpm dev

Für die lokale Entwicklung lädt Wrangler Umgebungsvariablen automatisch aus Ihrer .dev.vars-Datei.

Führen Sie vor der Bereitstellung alle Prüfungen aus:

pnpm build

Dieser Befehl führt Folgendes aus:

1. pnpm format - Code mit Biome formatieren

2. pnpm lint:fix - Lint-Probleme beheben

3. pnpm cf-typegen - Cloudflare-Typen generieren

4. pnpm type-check - TypeScript-Typen prüfen

Server testen:

# An unauthenticated request must return HTTP 401
curl -i http://localhost:8787/mcp

# Claude Code performs the authenticated MCP handshake and health check
claude mcp list

Debugging

Authentifizierung testen

Sie können überprüfen, dass der Endpunkt Anfragen ohne sein Bearer-Token ablehnt:

curl -i http://localhost:8787/mcp

Dies sollte 401 Unauthorized zurückgeben. Verwenden Sie dann claude mcp list, um eine authentifizierte Client-Verbindung zu überprüfen.

Häufige Probleme

1. 401 Unauthorized: Stellen Sie sicher, dass der Authorization: Bearer ...-Header des Clients mit dem Cloudflare-Secret MCP_AUTH_TOKEN übereinstimmt.

2. MCP verbindet sich erneut oder es kommt zu Zeitüberschreitungen: Stellen Sie sicher, dass der Client den HTTP-Transport und den /mcp-Endpunkt verwendet, nicht den eingestellten /sse-Endpunkt.

3. Telegram-Benachrichtigungen werden nicht gesendet: Überprüfen Sie, ob BOT_TOKEN und DEFAULT_CHAT_ID in der Worker-Umgebung korrekt festgelegt sind.

Technische Details

• Sprache: TypeScript (ES2021-Ziel)

• Laufzeit: Cloudflare Workers mit Node.js-Kompatibilität

• Protokoll: MCP (Model Context Protocol)

• Transport: Zustandsloses Streamable HTTP

• Observability: Für Monitoring aktiviert

Referenzen

Dieses Projekt wurde anhand der folgenden Anleitungen erstellt:

• Build a Remote MCP server - Cloudflare Agents

• Model Context Protocol (MCP) - Cloudflare Agents

• MCP Transport Methods - Cloudflare Agents

• Cloudflare MCP Template (remote-mcp-authless)

Lizenz

MIT