YOURLS-MCP

Ein Model Control Protocol (MCP)-Server zur Integration der YOURLS-URL-Verkürzung in Claude Desktop.

Autor: Martin Kessler

Überblick

YOURLS-MCP bildet eine Brücke zwischen Claude Desktop und Ihrer selbst gehosteten YOURLS -URL-Shortener-Instanz. Nach der Konfiguration ermöglicht es Claude, URLs mithilfe Ihrer persönlichen YOURLS-Installation automatisch zu kürzen.

Related MCP server: MCP Tools

Merkmale

• Kürzen Sie URLs mit Ihrer YOURLS-Instanz

• Erstellen Sie benutzerdefinierte Kurz-URLs mit bestimmten Schlüsselwörtern

• Umgang mit doppelten URLs: Erstellen Sie mehrere Kurz-URLs für dieselbe Ziel-URL (eindeutig für YOURLS-MCP).

• Erweiterte URL-Informationen und Statistiken

• Datenbankstatistiken

• Intelligente Fallbacks für Plugins

• Umfassende Dokumentation und Testtools

Schnellstart

Installation

Konfiguration

Erstellen Sie eine Claude Desktop-Konfigurationsdatei, die auf Ihre YOURLS-MCP-Installation verweist:

Speichern Sie diese Datei in Ihrem Claude Desktop-Konfigurationsverzeichnis. Normalerweise ist das:

• macOS: ~/Library/Application Support/Claude/config.json

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

• Linux: ~/.config/Claude/config.json

Merkmale

• Nahtlose Integration mit Claude Desktop über MCP

• URLs direkt über Claude kürzen

• Erweitern Sie verkürzte URLs, um ihr Ziel anzuzeigen

• Abrufen von Klickstatistiken für Ihre Links

• Unterstützung benutzerdefinierter Schlüsselwörter

• Sichere signaturbasierte Authentifizierung

• Konfiguration der Umgebungsvariablen

Konfigurationsoptionen

Die folgenden Umgebungsvariablen können in der Claude Desktop-Konfiguration festgelegt werden:

Verfügbare MCP-Tools

YOURLS-MCP stellt Claude die folgenden Tools zur Verfügung:

Kernwerkzeuge

1. URL verkürzen

Verkürzt eine lange URL mithilfe Ihrer YOURLS-Instanz.

Parameter:

• url (erforderlich): Die lange URL, die gekürzt werden soll

• keyword (optional): Benutzerdefiniertes Schlüsselwort für die Kurz-URL

• title (optional): Titel für die URL

2. expand_url

Erweitert eine kurze URL, um die ursprüngliche lange URL zu erhalten.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort zum Erweitern

3. url_stats

Ruft Statistiken für eine verkürzte URL ab.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort, für das Statistiken abgerufen werden sollen

4. db_stats

Ruft globale Statistiken für Ihre YOURLS-Instanz ab.

Parameter: Keine

5. benutzerdefinierte URL erstellen

Erstellt eine benutzerdefinierte Kurz-URL mit einem bestimmten Schlüsselwort, auch für URLs, die bereits in der Datenbank vorhanden sind.

Parameter:

• url (erforderlich): Die zu kürzende Ziel-URL

• keyword (erforderlich): Das benutzerdefinierte Schlüsselwort für die Kurz-URL (z. B. „Web“ für bysha.pe/web)

• title (optional): Titel für die URL

• bypass_shortshort (optional): Ob das ShortShort-Plugin umgangen werden soll, das das Kürzen bereits gekürzter URLs verhindert (Standard: false)

• force_url_modification (optional): Ob die Verwendung der URL-Änderungsmethode zum Erstellen mehrerer Kurz-URLs für dasselbe Ziel erzwungen werden soll (Standard: „false“)

6. Verkürzen mit Analytics

Verkürzt eine lange URL mit Google Analytics UTM-Parametern.

Parameter:

• url (erforderlich): Die zu kürzende URL

• source (erforderlich): UTM-Quellparameter – identifiziert die Quelle des Datenverkehrs (z. B. „Google“, „Newsletter“, „Twitter“)

• medium (erforderlich): UTM-Mediumparameter – identifiziert das Marketingmedium (z. B. „CPC“, „Soziales“, „E-Mail“)

• campaign (erforderlich): UTM-Kampagnenparameter – identifiziert die spezifische Kampagne (z. B. „summer_sale“, „product_launch“)

• term (optional): UTM-Term-Parameter – identifiziert bezahlte Suchbegriffe

• content (optional): UTM-Inhaltsparameter - unterscheidet Anzeigen oder Links, die auf dieselbe URL verweisen

• keyword (optional): Benutzerdefiniertes Schlüsselwort für die Kurz-URL

• title (optional): Titel für die URL

Plugin-basierte Tools

7. url_analytics

Ruft detaillierte Klickanalysen für eine Kurz-URL innerhalb eines bestimmten Zeitraums ab. Erfordert die Installation des API ShortURL Analytics-Plugins.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort, für das Analysen abgerufen werden sollen

• date (erforderlich): Startdatum für die Analyse im Format JJJJ-MM-TT

• date_end (optional): Enddatum für die Analyse im Format JJJJ-MM-TT (standardmäßig das Startdatum, falls nicht angegeben)

8. Vertrags-URL

Prüft, ob eine URL bereits gekürzt wurde, ohne eine neue Kurz-URL zu erstellen. Erfordert die Installation des API Contract-Plugins.

Parameter:

• url (erforderlich): Die URL, um zu überprüfen, ob sie gekürzt wurde

9. URL aktualisieren

Aktualisieren Sie eine vorhandene Kurz-URL, sodass sie auf eine andere Ziel-URL verweist. Dazu muss das API-Plugin „URL bearbeiten“ installiert sein.

Parameter:

• shorturl (erforderlich): Die zu aktualisierende Kurz-URL oder das Schlüsselwort

• url (erforderlich): Die neue Ziel-URL

• title (optional): Optionaler neuer Titel („behalten“, um den vorhandenen beizubehalten, „auto“, um ihn von der URL abzurufen)

10. Schlüsselwort ändern

Ändern Sie das Schlüsselwort einer bestehenden Kurz-URL. Dazu muss das API-Plugin „URL bearbeiten“ installiert sein.

Parameter:

• oldshorturl (erforderlich): Die vorhandene Kurz-URL oder das Schlüsselwort

• newshorturl (erforderlich): Das neue zu verwendende Schlüsselwort

• url (optional): Optionale URL (falls nicht angegeben, wird die URL von oldshorturl verwendet)

• title (optional): Optionaler neuer Titel („behalten“, um den vorhandenen beizubehalten, „auto“, um ihn von der URL abzurufen)

11. URL-Schlüsselwort abrufen

Holen Sie sich die Schlüsselwörter für eine lange URL. Dazu muss das API-Plugin „URL bearbeiten“ installiert sein.

Parameter:

• url (erforderlich): Die lange URL zum Nachschlagen

• exactly_one (optional): Wenn false, werden alle Schlüsselwörter für diese URL zurückgegeben (Standard: true)

12. URL löschen

Löscht eine Kurz-URL. Dazu muss das Plugin „API Delete“ installiert sein.

Parameter:

• shorturl (erforderlich): Die zu löschende Kurz-URL oder das Schlüsselwort

13. list_urls

Erhalten Sie eine Liste von URLs mit Sortier-, Paginierungs- und Filteroptionen. Erfordert die Installation des Plugins „API List Extended“.

Parameter:

• sortby (optional): Feld zum Sortieren nach (Schlüsselwort, URL, Titel, IP, Zeitstempel, Klicks) (Standard: Zeitstempel)

• sortorder (optional): Sortierreihenfolge (ASC oder DESC) (Standard: DESC)

• offset (optional): Paginierungsoffset (Standard: 0)

• perpage (optional): Anzahl der Ergebnisse pro Seite (Standard: 50)

• query (optional): Optionale Suchabfrage zum Filtern nach Schlüsselwörtern

• fields (optional): Zurückzugebende Felder (Schlüsselwort, URL, Titel, Zeitstempel, IP, Klicks) (Standard: alle Felder)

14. QR-Code generieren

Generieren Sie einen QR-Code für eine verkürzte URL. Erfordert die Installation des Plugins YOURLS-IQRCodes.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort zum Generieren eines QR-Codes für

• size (optional): QR-Code-Größe in Pixeln

• border (optional): Rahmenbreite um den QR-Code

• ecc (optional): Fehlerkorrekturstufe: L (niedrig), M (mittel), Q (Quartil) oder H (hoch)

• format (optional): Bildformat (png, jpg, svg usw.)

Anwendungsbeispiele

Nach der Konfiguration kann Claude die YOURLS-Tools mit Eingabeaufforderungen wie den folgenden verwenden:

Beispiele für Kernfunktionen

• „Kürzen Sie diese URL für mich: https://example.com/sehr-lange-url-die-gekürzt-werden-muss “

• „Erstellen Sie eine kurze URL mit dem Schlüsselwort ‚docs‘ für https://example.com/documentation “

• „Richten Sie eine benutzerdefinierte URL bysha.pe/web ein, die auf shapescale.com verweist.“

• „Erstellen Sie eine benutzerdefinierte Kurz-URL für unsere Dokumentation mit dem Schlüsselwort ‚docs‘.“

• „Erstellen Sie mehrere Schlüsselwörter (docs, docs2, docs3) für dieselbe Dokumentations-URL.“

• „Erstellen Sie eine kurze URL für unsere Kampagne mit UTM-Tracking-Parametern“

• „Kürzen Sie diese Marketing-URL mit Google Analytics-Tracking: Quelle=Newsletter, Medium=E-Mail, Kampagne=Sommerstart“

• "Erweitern Sie diese kurze URL: https://IhreDomain.com/abc "

• „Wie viele Klicks hat meine Kurz-URL https://yourdomain.com/abc ?“

• „Zeigen Sie mir die Statistiken für meine YOURLS-Instanz“

Beispiele für Plugin-basierte Funktionen

• „Geben Sie mir detaillierte Analysen für die Kurz-URL ‚abc‘ für Januar 2025.“

• „Zeigen Sie mir die Klickstatistiken für bysha.pe/abc vom 01.01.2025 bis zum 31.01.2025“

• „Wie hoch war der tägliche Datenverkehr für meine Kurz-URL ‚Web‘ im letzten Monat?“

• „Überprüfen Sie, ob diese URL bereits gekürzt wurde: https://example.com/page “

• „Hat jemand bereits eine Kurz-URL für https://example.com/page erstellt?“

• „Aktualisieren Sie das Ziel der Kurz-URL ‚docs‘, sodass es auf https://example.com/new-documentation verweist.“

• „Ändern Sie, wohin das Schlüsselwort ‚docs‘ verweist.“

• „Benennen Sie die Kurz-URL ‚docs‘ in ‚documentation‘ um.“

• „Ändern Sie das Schlüsselwort meiner Kurz-URL von ‚docs‘ in ‚documentation‘.“

• „Was ist das Schlüsselwort für diese lange URL: https://example.com/page ?“

• "Liste alle Kurz-URLs für https://example.com/page auf"

• „Löschen Sie die Kurz-URL ‚docs‘“

• „Entfernen Sie das Schlüsselwort ‚docs‘ aus meiner YOURLS-Instanz.“

• „Zeigen Sie mir die aktuellsten 10 Kurz-URLs in meiner YOURLS-Datenbank“

• "Liste alle Kurz-URLs sortiert nach der Anzahl der Klicks auf"

• „Suchen Sie nach kurzen URLs, die ‚Produkt‘ enthalten.“

• „Generieren Sie einen QR-Code für meine Kurz-URL ‚docs‘“

• „Erstellen Sie einen QR-Code für bysha.pe/web“

• „Geben Sie mir einen QR-Code für meine Produktseite mit hoher Fehlerkorrektur“

• „Ich brauche einen größeren QR-Code für die ‚Landing‘-Kurz-URL, also 300 Pixel.“

• „Generieren Sie einen SVG-QR-Code für unseren Dokumentationslink.“

Entwicklung

Wie es funktioniert

YOURLS-MCP fungiert als Brücke zwischen Claude Desktop und Ihrer YOURLS-Instanz:

1. Claude Desktop startet den YOURLS-MCP-Server bei Bedarf

2. Der Server liest die Konfiguration aus Umgebungsvariablen

3. Wenn Claude ein Tool aufruft, führt der Server die entsprechenden API-Aufrufe an Ihre YOURLS-Instanz durch

4. Die Ergebnisse werden Claude in einem strukturierten Format zurückgegeben

Der Server verwendet den Model Context Protocol (MCP)-Standard zur Kommunikation mit Claude Desktop und ermöglicht so eine nahtlose Integration und natürliche Sprachinteraktion mit Ihrem URL-Shortener.

Umgang mit doppelten URLs

YOURLS-MCP bietet die einzigartige Möglichkeit, mehrere Kurz-URLs für dieselbe Ziel-URL zu erstellen. Diese Funktion wird von YOURLS nicht nativ unterstützt. Ausführliche Informationen zu dieser Funktion finden Sie in der Dokumentation zur Handhabung doppelter URLs .

Es werden zwei Ansätze unterstützt:

1. Plugin-Ansatz (empfohlen): Verwendet das enthaltene Plugin „Force Allow Duplicates“, um echte doppelte URLs zu erstellen

2. URL-Modifikationsansatz (Fallback): Fügt Zeitstempelparameter hinzu, um jede URL technisch eindeutig zu machen und gleichzeitig die Funktionalität zu erhalten

Das System wählt automatisch den geeigneten Ansatz basierend auf Ihrem YOURLS-Setup.

Kompatibilität mit YOURLS-Plugins

YOURLS-MCP ist so konzipiert, dass es sowohl mit Standard-YOURLS-Installationen als auch mit verschiedenen Plugins funktioniert, mit integrierten Fallbacks, wenn Plugins nicht verfügbar sind:

Unterstützte Plugins mit Fallbacks

YOURLS-MCP enthält intelligente Fallbacks für erweiterte Funktionen, wenn keine Plugins installiert sind:

• API ShortURL Analytics : Für detaillierte Klickstatistiken mit Datumsbereichen

  • Fallback-Verhalten : Bietet grundlegende Klickstatistiken über die YOURLS-Kern-API, wenn das Plugin nicht verfügbar ist

• API-Vertrag : Um zu prüfen, ob URLs vorhanden sind, ohne sie zu erstellen

  • Fallback-Verhalten : Verwendet die Kern-API von YOURLS Stats, um mit Filterung nach vorhandenen URLs zu suchen

• API-URL bearbeiten : Zum Aktualisieren kurzer URLs und Ändern von Schlüsselwörtern

  • Fallback-Verhalten :

    • Zum Aktualisieren von URLs: Versuche, die URL mit demselben Schlüsselwort neu zu erstellen

    • Zum Ändern von Schlüsselwörtern: Erstellt eine neue Kurz-URL mit dem neuen Schlüsselwort (die alte bleibt erhalten, da zum Löschen das API Delete-Plugin erforderlich ist)

    • Zum Abrufen von URL-Schlüsselwörtern: Verwendet die Kern-API YOURLS-Statistiken mit Filterung

• API Delete : Zum Entfernen kurzer URLs

  • Fallback-Verhalten : Eingeschränkt – bietet Informationen darüber, dass zum Löschen das Plugin erforderlich ist, da die Kern-API von YOURLS das Löschen nicht unterstützt

• API-Liste erweitert : Für eine erweiterte URL-Auflistung mit Sortierung und Filterung

  • Fallback-Verhalten : Verwendet die Kern-API von YOURLS-Statistiken mit clientseitiger Sortierung und Paginierung

• YOURLS-IQRCodes : Zum Generieren von QR-Codes aus Kurz-URLs

  • Fallback-Verhalten : Keines – erfordert die Installation des Plugins

• ShortShort : Behandelt den Fehler ordnungsgemäß, wenn versucht wird, eine bereits gekürzte URL zu kürzen

  • Kompatibilität : Die Fehlerbehandlung funktioniert unabhängig davon, ob das Plugin installiert ist

• Vorhandene URLs zulassen : Ändert, wie YOURLS mit doppelten URLs umgeht

  • Plugin-URL : https://github.com/elder-oss/yourls-allow-existing-urls

  • Hinweis : Dieses Plugin ändert Fehlerantworten in Erfolgsantworten, erstellt aber keine neuen Kurz-URLs für bestehende Ziel-URLs.

  • Unsere Lösung : YOURLS-MCP implementiert einen URL-Modifikationsansatz, der einen Zeitstempelparameter hinzufügt, um URLs in der Datenbank eindeutig zu machen und gleichzeitig die Benutzererfahrung zu erhalten

  • Installation : Optional – unser Ansatz zur URL-Änderung funktioniert mit oder ohne installiertes Plugin

• Duplikate zulassen erzwingen : Ermöglicht das Erstellen mehrerer kurzer URLs für dieselbe Ziel-URL.

  • Plugin-Repository : https://github.com/kesslerio/yourls-force-allow-duplicates (in Kürze verfügbar)

  • Beschreibung : Benutzerdefiniertes Plugin, das die eindeutige URL-Einschränkung von YOURLS umgeht

  • Verwendung : Fügen Sie force=1 zu Ihren API-Anfragen hinzu oder verwenden Sie force_url_modification=false mit dem Tool create_custom_url

  • Installation :

    1. Download aus dem Plugin-Repository

    2. Kopieren Sie den Ordner force-allow-duplicates in Ihr Verzeichnis YOURLS/user/plugins/

    3. Aktivieren Sie das Plugin in Ihrer YOURLS-Admin-Oberfläche

Fallback-Mechanismus

Wenn eine Plugin-abhängige Funktion verwendet wird, das Plugin aber nicht installiert ist, führt YOURLS-MCP Folgendes aus:

1. Erkennt automatisch fehlende Plugins

2. Bietet, soweit möglich, entsprechende Fallback-Funktionen

3. Enthält ein fallback_used: true Attribut in Antworten, wenn Fallbacks aktiviert sind

4. Fügt fallback_limitations -Informationen hinzu, wenn die Fallback-Funktionalität eingeschränkt ist

5. Gibt bei vollständig nicht unterstützten Vorgängen informative Fehlermeldungen zurück

Dieser Ansatz stellt sicher, dass YOURLS-MCP mit möglichst vielen YOURLS-Installationen funktioniert und gleichzeitig klare Informationen über die mit Plugins verfügbaren erweiterten Funktionen bereitstellt.

Entwicklung und Tests

Testskripte

Das Projekt enthält verschiedene Testskripte im Verzeichnis tests/integration/ :

• URL-Verkürzungstests :

  • test-custom-url.js : Tests zum Erstellen benutzerdefinierter URLs mit bestimmten Schlüsselwörtern

  • test-url-modification.js : Testet den URL-Änderungsansatz für den Umgang mit doppelten URLs

  • test-plugin-behavior.js : Testet das Verhalten des Plugins „Vorhandene URLs zulassen“

• Plugin-Tests :

  • test-duplicate-urls.js : Testet das Erstellen doppelter URLs mit unterschiedlichen Schlüsselwörtern

  • test-plugin-approach.js : Testet den direkten Plugin-Ansatz zur Handhabung von Duplikaten

• Laufende Tests :

  # Run a specific test node tests/integration/test-custom-url.js

Hilfsskripte

Das Verzeichnis scripts/ enthält Dienstprogrammskripte für allgemeine Vorgänge:

• create-random.js : Erstellt eine zufällige Kurz-URL für ein angegebenes Ziel

• Andere Skripte für bestimmte Aufgaben zur URL-Erstellung

Lizenz

MIT

Um

YOURLS-MCP wurde von Martin Kessler entwickelt, um YOURLS über das Model Context Protocol (MCP) mit Claude Desktop und anderen Claude-Angeboten zu integrieren.

Das Plugin „Force Allow Duplicates“ wurde entwickelt, um das Problem der Erstellung mehrerer Kurz-URLs für dasselbe Ziel zu lösen, was in YOURLS nicht nativ unterstützt wird.

Für Support, Probleme oder Funktionsanfragen:

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues

• Plugin „Force Allow Duplicates“: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (sobald das Repository erstellt ist)