Ntfy MCP-Server

Ein MCP-Server (Model Context Protocol) für die Interaktion mit dem ntfy -Push-Benachrichtigungsdienst. Er ermöglicht LLMs und KI-Agenten, Benachrichtigungen mit umfangreichen Anpassungsmöglichkeiten an Ihre Geräte zu senden.

Inhaltsverzeichnis

• Überblick

• Merkmale

• Schnellstart

• Installation

• Konfiguration

• Projektstruktur

• Werkzeuge

• Ressourcen

• Anwendungsfälle

• Verfügbare Skripte

• Beitragen

• Lizenz

Überblick

Dieser Server implementiert das Model Context Protocol (MCP) und ermöglicht so die standardisierte Kommunikation zwischen LLMs und externen Systemen. Insbesondere stellt er eine Schnittstelle zum ntfy-Push-Benachrichtigungsdienst bereit.

Ntfy ist ein einfacher HTTP-basierter Pub-Sub-Benachrichtigungsdienst, mit dem Sie Benachrichtigungen über einfache HTTP-Anfragen an Ihr Smartphone oder Ihren Desktop senden können. Mit diesem MCP-Server können LLM-Agenten wie Claude Ihnen Benachrichtigungen über ntfy senden, ohne direkten HTTP-Zugriff zu benötigen.

Merkmale

• MCP-Serverimplementierung: Erstellt mit @modelcontextprotocol/sdk für nahtlose Integration mit LLM-Agenten.

• Ntfy-Integration: Bietet ein Tool ( send_ntfy ) zum Senden von Benachrichtigungen mit Unterstützung für:

  • Nachrichtenpriorisierung (1-5 Stufen)

  • Emoji-Tags

  • Anklickbare Aktionen und Schaltflächen

  • Dateianhänge

  • Verspätete Lieferung

  • Markdown-Formatierung

• Ressourcenfreigabe: Macht das konfigurierte Standard-NTFY-Thema als MCP-Ressource verfügbar.

• TypeScript: Moderne, typsichere Codebasis mit umfassenden Typdefinitionen.

• Strukturierte Protokollierung: Verwendet winston und winston-daily-rotate-file für detaillierte und rotierende Protokolle.

• Konfigurationsverwaltung: Verwendet dotenv für eine einfache umgebungsbasierte Konfiguration.

• Dienstprogrammskripte: Enthält Skripte zum Bereinigen von Build-Artefakten und zum Generieren einer Verzeichnisstrukturdokumentation.

• Fehlerbehandlung und Sicherheit: Implementiert eine robuste Fehlerbehandlung, Eingabebereinigung ( sanitize-html ) und Sicherheitsfilter ( xss-filters ).

Schnellstart

1. Voraussetzungen:

   • Node.js (v16+)

   • npm oder yarn

   • Ein MCP-kompatibler Client (Claude Desktop, Cline usw.)

2. Installieren und ausführen:

   # Option 1: Install via npm npm install -g ntfy-mcp-server # Option 2: Clone repository and build git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server npm install npm run build # Create .env file (optional but recommended) cp .env.example .env # Edit .env to set NTFY_DEFAULT_TOPIC # Start the server npm start

3. Zu den MCP-Client-Einstellungen hinzufügen: Fügen Sie den Server zu Ihrer MCP-Client-Einstellungsdatei hinzu (siehe Konfiguration ).

4. Verwenden Sie das Tool: Sobald die Verbindung hergestellt ist, können Sie das Tool send_ntfy verwenden, um Benachrichtigungen zu senden.

Installation

Option 1: NPM-Paket (empfohlen)

1. Installieren Sie das Paket global:

   npm install -g ntfy-mcp-server

   Dadurch wird der Server global installiert und als Befehlszeilentool verfügbar gemacht.

2. Oder installieren Sie es lokal in Ihrem Projekt:

   npm install ntfy-mcp-server

   Bei lokaler Installation können Sie es über npx oder vom Knoten aus ausführen.

Option 2: Aus der Quelle

1. Klonen Sie das Repository:

   git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server

2. Installieren Sie Abhängigkeiten:

   npm install

3. Erstellen Sie das Projekt:

   npm run build

Konfiguration

Umgebungsvariablen

Erstellen Sie eine .env Datei im Projektstamm basierend auf .env.example :

MCP-Client-Einstellungen

Für die Cline VSCode-Erweiterung

Fügen Sie Ihrer Cline MCP-Einstellungsdatei (unter macOS normalerweise unter ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ) die folgende Konfiguration hinzu:

Bei globaler Installation:

Bei Installation aus der Quelle:

Für Claude Desktop App

Fügen Sie Ihrer Claude Desktop-Konfigurationsdatei die folgende Konfiguration hinzu (unter macOS normalerweise unter ~/Library/Application Support/Claude/claude_desktop_config.json ):

Bei globaler Installation:

Bei Installation aus der Quelle:

Ersetzen Sie bei der Quellinstallation Passen Sie

Ntfy-Einrichtung

1. Installieren Sie die ntfy-App auf Ihren Geräten von ntfy.sh oder den App Stores

2. Abonnieren Sie Ihr Thema in der App

3. Verwenden Sie dasselbe Thema in Ihrer MCP-Serverkonfiguration

Projektstruktur

Werkzeuge

send_ntfy

Sendet eine Benachrichtigungsnachricht über den ntfy-Dienst.

Hauptargumente:

Anwendungsbeispiel:

Beispielantwort:

Ressourcen

Direkte Ressourcen

ntfy://default

• Beschreibung: Gibt das in den Umgebungsvariablen des Servers konfigurierte Standard-NTFY-Thema zurück ( NTFY_DEFAULT_TOPIC ).

• Verwendung: Nützlich für Clients, um das Hauptthema zu entdecken, ohne dass eine vorherige Konfiguration erforderlich ist.

• Beispiel: Ein LLM-Agent kann auf diese Ressource zugreifen, um beim Senden von Benachrichtigungen automatisch das Standardthema zu verwenden.

• Beispielantwort:

  { "defaultTopic": "ATLAS", "timestamp": "2025-03-27T08:30:25.619Z", "requestUri": "ntfy://default", "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484" }

Ressourcenvorlagen

ntfy://{topic}

• Beschreibung: Gibt Informationen zu einem bestimmten NTFY-Thema zurück.

• Parameter: topic – Der Name des NTFY-Themas.

• Verwendung: Zum Abfragen von Informationen zu anderen Themen als den Standardthemen.

• Beispielantwort:

  { "topic": "ATLAS", "timestamp": "2025-03-27T08:30:30.038Z", "requestUri": "ntfy://ATLAS", "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0" }

Anwendungsfälle

1. Benachrichtigungen zu lang laufenden Aufgaben – Lassen Sie sich benachrichtigen, wenn Aufgaben wie Datenbanksicherungen, Codegenerierung oder Datenverarbeitung abgeschlossen sind.

2. Geplante Erinnerungen – Legen Sie verzögerte Benachrichtigungen für zukünftige Ereignisse oder Erinnerungen fest.

3. Warnsysteme – Richten Sie kritische Warnmeldungen für Überwachungssysteme oder wichtige Ereignisse ein.

4. Mobile Benachrichtigungen von LLMs – Erlauben Sie LLMs, Benachrichtigungen direkt an Ihr Telefon zu senden.

5. Mehrstufige Prozessaktualisierungen – Erhalten Sie Aktualisierungen, wenn verschiedene Phasen eines komplexen Prozesses abgeschlossen sind.

Anwendungsbeispiele

Grundlegende Benachrichtigung

Umfangreiche Benachrichtigungen mit Aktionen

Verfügbare Skripte

• npm run build : Kompiliert den TypeScript-Quellcode im Verzeichnis dist/ in JavaScript.

• npm run clean : Entfernt das Verzeichnis dist/ und bereinigt den Inhalt des Verzeichnisses logs/ .

• npm run rebuild : Läuft clean und build dann.

• npm run tree : Generiert eine Verzeichnisbaumdarstellung in docs/tree.md .

• npm start : Führt den kompilierten Server mithilfe von Node.js aus dem Verzeichnis dist/ aus.

• npm run watch : Durchsucht die kombinierte Protokolldatei ( logs/combined.log ) zur Echtzeitüberwachung.

Beitragen

Beiträge sind willkommen! Senden Sie gerne Pull Requests oder offene Probleme, um das Projekt zu verbessern.

1. Forken Sie das Repository.

2. Erstellen Sie einen Feature-Zweig ( git checkout -b feature/your-feature ).

3. Übernehmen Sie Ihre Änderungen ( git commit -m 'Add some feature' ).

4. Pushen Sie zum Zweig ( git push origin feature/your-feature ).

5. Erstellen Sie eine neue Pull-Anfrage.

Erstellen Sie bei Fehlern und Funktionsanfragen bitte ein Problem im Repository.

Bewährte Methoden für die Entwicklung

• Befolgen Sie die Best Practices von TypeScript und achten Sie auf eine korrekte Typisierung

• Schreiben Sie Tests für neue Funktionen

• Halten Sie Abhängigkeiten auf dem neuesten Stand

• Befolgen Sie den vorhandenen Codestil und die vorhandenen Muster

Lizenz

Dieses Projekt ist unter der Apache-2.0-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE .

Danksagung

• ntfy.sh zur Bereitstellung des Benachrichtigungsdienstes

• Model Context Protocol zur Ermöglichung von LLM-zu-Tool-Verbindungen

• Alle Mitwirkenden und Benutzer dieses Projekts