linkwarden-mcp

Ein Model Context Protocol-Server für Linkwarden, den selbst gehosteten Lesezeichen-Manager, der eine permanente Kopie jeder gespeicherten Seite aufbewahrt.

Er ermöglicht einem MCP-Client – Claude Code, Claude Desktop, Codex – eine Lesezeichen-Sammlung zu durchsuchen, sie in Sammlungen und Tags zu organisieren und den gespeicherten Artikeltext einer archivierten Seite zu lesen, sodass ein archivierter Link zusammengefasst oder zitiert werden kann, ohne die Live-Seite erneut abrufen zu müssen.

📖 Vollständige Dokumentation unter linkwarden-mcp.ni-c.de

Hinweis: Die veröffentlichte API-Referenz von Linkwarden ist unvollständig. Dieser Server wurde anhand der Routen in apps/web/pages/api/v1/** und der Anforderungsschemata in packages/lib/schemaValidation.ts von linkwarden/linkwarden entwickelt, verifiziert gegen v2.16.0 vom 17.08.2026. Diese beiden Dateien sind die maßgebliche Quelle für jedes hier enthaltene Werkzeug.

Voraussetzungen

• Node.js ≥ 22

• Eine laufende Linkwarden-Instanz

• Ein Zugriffstoken, erstellt unter Einstellungen → Zugriffstoken

Linkwarden hat keine bereichsspezifischen Token: Ein Token trägt die vollständigen Berechtigungen des Kontos, das es erstellt hat. Erstellen Sie ein dediziertes Konto mit Zugriff nur auf die Sammlungen, die dieser Server sehen soll, anstatt ihm ein Admin-Token zu übergeben.

Related MCP server: linkwarden-mcp

Konfiguration

Verwenden Sie https://. Über einfaches http wird das Token unverschlüsselt übertragen; der Server gibt eine Warnung aus, es sei denn, der Host ist lokal. Für ein selbstsigniertes Zertifikat bevorzugen Sie eine ordnungsgemäße interne CA gegenüber LINKWARDEN_INSECURE_TLS.

Das Token wird aus der Prozessumgebung entfernt, sobald es gelesen wurde, sodass es für Kindprozesse oder in /proc/<pid>/environ nicht sichtbar ist.

Ohne Anmeldedaten startet der Server trotzdem und listet seine Werkzeuge auf, sodass Registrierungen und Inspektoren ihn untersuchen können; jeder Aufruf schlägt dann mit Einrichtungsanweisungen fehl, anstatt die API zu erreichen.

Installation

Claude Code

claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp

Claude Desktop

{
  "mcpServers": {
    "linkwarden": {
      "command": "npx",
      "args": ["-y", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_URL": "https://links.example.net",
        "LINKWARDEN_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.linkwarden]
command = "npx"
args = ["-y", "linkwarden-mcp"]
env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }

Aus dem Quellcode

npm install && npm run build
LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js

Docker

docker build -t linkwarden-mcp .
docker run --rm -i \
  -e LINKWARDEN_URL=https://links.example.net \
  -e LINKWARDEN_TOKEN=… \
  linkwarden-mcp

Werkzeuge

Lesen

Schreiben

Wird bei LINKWARDEN_READ_ONLY=true überhaupt nicht registriert. Mit 🔒 gekennzeichnete Werkzeuge erfordern einen Bestätigungs-Token.

Bewusst nicht bereitgestellt

• Zugriffstoken-Verwaltung (/tokens). Ein Werkzeug, das API-Anmeldedaten ausstellen kann, ist eine Angriffsfläche für Privilegienausweitung, und ein Lesezeichen-Server hat keinen Grund, eines zu besitzen.

• Benutzerverwaltung (/users, Kontolöschung). Nicht im Rahmen.

• Backup-Export und -Import (/migration). Der Export gibt die gesamte Instanz in den Kontext des Modells; der Import kann sie zerstören.

• Hervorhebungen. Das Erstellen einer Hervorhebung benötigt exakte Zeichen-Offsets im archivierten Dokument, die ein Modell nicht sinnvoll erzeugen kann, und Linkwarden bietet keine Route zum Auflisten vorhandener Hervorhebungen.

• Archiv-Uploads und die signierten preserved-URLs, die NEXT_PUBLIC_USER_CONTENT_DOMAIN konfiguriert benötigen.

• Die veraltete GET /links-Auflistungsroute – search_links verwendet stattdessen GET /search, was Linkwarden selbst empfiehlt.

Sicherheit

• Destruktive Werkzeuge sind zweistufig. Der erste Aufruf gibt einen kurzlebigen Bestätigungs-Token zurück, der an das genaue Ziel gebunden ist; erst ein zweiter Aufruf mit diesem Token führt die Operation aus. Ein Modell kann diese Hürde nicht allein überwinden, und ein Token, der für einen Link, eine Tag-Menge oder eine Änderung ausgestellt wurde, kann nicht für eine andere wiederverwendet werden.

• Sichtbarkeitserweiterung gilt als destruktiv. Das Veröffentlichen einer Sammlung und das Ändern der URL eines Links – was jede archivierte Kopie der alten Seite löscht – erfordern beide eine Bestätigung, nicht nur Löschungen.

• Bestätigungsaufforderungen zitieren niemals Inhalte aus Linkwarden. Titel, URLs, Beschreibungen und Sammlungsnamen stammen von archivierten Seiten und von anderen Benutzern der Instanz; nur Anzahlen und IDs erscheinen im Text, den ein Modell liest.

• Zurückgegebene Inhalte werden als nicht vertrauenswürdige Daten markiert, insbesondere der gespeicherte Artikeltext, der von demjenigen geschrieben wurde, der die Zielseite kontrolliert.

• Teilaktualisierungen leeren niemals Felder. Linkwardens Aktualisierungsrouten ersetzen den gesamten Datensatz, daher liest dieser Server den aktuellen Zustand und führt eine Zusammenführung durch – andernfalls würde eine Aktualisierung stillschweigend die Tags eines Links oder die Mitarbeiter einer Sammlung entfernen.

• Ein HTTP 200 wird nicht allein als vertrauenswürdig angesehen. Mehrere Linkwarden-Routen melden Fehler mit HTTP 200 und einem Fehlersatz im Body, und eine Route ohne Handler für die verwendete Methode antwortet mit 200 und gar nichts. Beides wird als Fehler gemeldet, nicht als erfolgreicher Schreibvorgang.

• Fehler-Bodies werden abgeschnitten, HTML-Fehlerseiten werden vollständig verworfen, Weiterleitungen werden niemals verfolgt (damit das Bearer-Token nicht an einen anderen Host weitergegeben werden kann), und jede Anfrage hat ein Timeout.

• LINKWARDEN_READ_ONLY=true registriert die Schreibwerkzeuge überhaupt nicht.

• Restrisiko: Innerhalb der Berechtigungen des von Ihnen konfigurierten Tokens kann ein Modell, das aufgefordert wird, etwas Destruktives zu tun und von einem Benutzer bestätigt wird, dies dennoch tun. Beschränken Sie das Konto und behalten Sie hostseitige Berechtigungsaufforderungen bei.

Entwicklung

npm install
npm run build
npm test
npm run test:coverage
npm run lint
npm run format
npm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md wird generiert; CI schlägt fehl, wenn die eingecheckte Kopie nicht mehr mit dem Code übereinstimmt. Die Dokumentationsseite befindet sich in docs/ mit eigener package.json und Lockfile – VitePress darf nicht in der Root-Installation landen, die im Docker-Build und über die gesamte Testmatrix hinweg ausgeführt wird.

Siehe CONTRIBUTING.md.

Veröffentlichung

Alles wird durch einen Tag gesteuert; es gibt keinen manuellen Veröffentlichungsschritt.

1. Verschiebe den Abschnitt [Unreleased] der CHANGELOG.md in die neue Version und datiere ihn. Der Release-Workflow extrahiert diesen Abschnitt mit awk, daher ist die Formatierung der Überschrift ## [x.y.z] wichtig.

2. Erhöhe version in package.json.

3. npm run lint && npm run build && npm run test:coverage.

4. Committen, dann einen signierten, annotierten Tag erstellen:

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1

release.yml prüft dann, ob der Tag mit package.json übereinstimmt, veröffentlicht über Trusted Publishing (OIDC – es existiert kein npm-Token, der auslaufen könnte) mit Provenance auf npm, synchronisiert die Version in beide server.json-Paketeinträge, veröffentlicht im MCP-Registry und erstellt das GitHub-Release aus dem Changelog-Abschnitt. ci.yml pusht parallel das Multi-Arch-Container-Image zu GHCR.

Falls der Registry-Schritt fehlschlägt, behebe ihn auf main und führe den Workflow mcp-registry.yml manuell aus. Die fehlgeschlagene Aufgabe erneut auszuführen ist keine Option: Sie checkt den unveränderlichen Tag aus, sodass eine Korrektur auf main ihn nie erreichen könnte.

License

MIT © Willi Thiel