freshrss-mcp

Ein Model Context Protocol-Server für FreshRSS, den selbst gehosteten RSS- und Atom-Feed-Aggregator.

Er spricht die Google-Reader-kompatible API, die FreshRSS unter /api/greader.php bereitstellt, und verbirgt deren Eigenheiten hinter Tool-Argumenten, die ein Assistent tatsächlich nutzen kann: numerische Feed-IDs, Kategorie- und Labelnamen, ISO-Daten und dezimale Artikel-IDs anstelle von user/-/state/com.google/…-Stream-Identifikatoren und hexadezimalen Item-Tags.

📖 Vollständige Dokumentation: freshrss-mcp.ni-c.de

Voraussetzungen

• Node.js 22 oder neuer

• Eine FreshRSS-Instanz (entwickelt gegen 1.29) mit

  • aktivierter API: Einstellungen → Authentifizierung → „API-Zugriff erlauben“

  • einem API-Passwort für den Benutzer: Einstellungen → Profil → API-Verwaltung. Dies ist ein separates Passwort vom Web-Login.

Related MCP server: Conduit

Konfiguration

Der Server startet ohne Anmeldedaten, sodass seine Tools auflistbar bleiben; jeder Aufruf schlägt dann mit diesen Einrichtungsanweisungen fehl.

Claude Code

claude mcp add freshrss -- npx -y @ni-c/freshrss-mcp

Claude Desktop

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": {
        "FRESHRSS_URL": "https://rss.example.com",
        "FRESHRSS_USER": "alice",
        "FRESHRSS_API_PASSWORD": "…"
      }
    }
  }
}

Codex

[mcp_servers.freshrss]
command = "npx"
args = ["-y", "@ni-c/freshrss-mcp"]
env = { FRESHRSS_URL = "https://rss.example.com", FRESHRSS_USER = "alice", FRESHRSS_API_PASSWORD = "…" }

Tools

Lesen

Schreiben

Nicht registriert, wenn FRESHRSS_READ_ONLY=true.

Keine Suche

FreshRSS bietet keine Volltextsuche über seine API – die Google-Reader-Endpunkte filtern nur nach Stream, Lesestatus und Datum. list_articles hat daher keinen Abfrageparameter; grenzen Sie das Ergebnis mit feed_id/category und since/until ein und filtern Sie die zurückgegebenen Artikel selbst.

Sicherheit

• Artikeltext ist nicht vertrauenswürdige Eingabe. Alles, was dieser Server von FreshRSS zurückgibt, wurde von einem Dritten im Internet geschrieben, daher werden Antworten, die Artikeltext, Titel oder Feednamen enthalten, explizit als Daten und nie als Anweisungen markiert.

• Zerstörerische Tools sind zweistufig. Sie geben ein einmalig verwendbares Bestätigungstoken zurück, das an das genaue Ziel gebunden ist; der zweite Aufruf muss es enthalten. Ein einfacher Boolean könnte bereits beim ersten Aufruf gesetzt oder durch in einem Feed versteckten Text dazu überredet werden. Die Bestätigungsnachrichten zitieren bewusst nie Titel oder Namen, die von der API stammen.

• Antwortbudgets. FreshRSS gibt bis zu 500.000 Zeichen HTML pro Artikel zurück. Artikeltext wird in Klartext umgewandelt, pro Artikel und gegen ein Pro-Antwort-Budget begrenzt und ist in Auflistungen nur optional.

• Anmeldedaten werden einmal gelesen, anschließend aus process.env entfernt und nie auf die Festplatte geschrieben. Anfragen folgen niemals Weiterleitungen, die den Autorisierungsheader an einen anderen Host senden würden, und die gelockerte TLS-Validierung ist auf diese Verbindung beschränkt, nicht auf den gesamten Prozess.

• Feed-URLs werden geschwärzt. FreshRSS speichert HTTP-auth-Feeds als https://user:password@host/feed. Der Benutzerinfo-Teil wird entfernt, bevor eine Feed-URL ein Tool-Ergebnis oder den OPML-Export erreicht, sodass list_feeds das Passwort eines kostenpflichtigen oder privaten Feeds nicht in das Transkript drucken kann.

• subscribe_feed lehnt interne Ziele ab. FreshRSS ruft die URL serverseitig ab, was das Tool zu einer SSRF-Primitive macht, die aus Text in einem Artikel erreichbar ist. Loopback- und Link-Local-Adressen – einschließlich Cloud-Metadaten-Endpunkte – werden abgelehnt. Private LAN-Adressen bleiben erlaubt, da selbst gehostete Installationen legitimerweise Feeds in ihrem eigenen Netzwerk abonnieren.

• import_opml lehnt ein <!DOCTYPE> ab. In diesem Prozess wird kein XML geparst, aber das Dokument wird an FreshRSS übergeben, wo eine Dokumenttypdeklaration der Träger für Entity-Expansion- und External-Entity-Angriffe ist. OPML benötigt niemals eine.

• FRESHRSS_READ_ONLY=true registriert die Schreib-Tools gar nicht erst, anstatt sie zur Aufrufzeit abzulehnen.

Welche Tools durch ein Bestätigungstoken geschützt sind: mark_all_as_read, unsubscribe_feed, delete_category_or_label und import_opml. mark_articles ist bewusst nicht geschützt – der Aufrufer nennt jeden der maximal 100 Artikel explizit und jedes Feld kann zurückgesetzt werden –, wird aber als zerstörerisch deklariert, sodass ein Client dennoch eine Bestätigung anfordern kann.

Container

docker run --rm -i \
  -e FRESHRSS_URL=https://rss.example.com \
  -e FRESHRSS_USER=alice \
  -e FRESHRSS_API_PASSWORD=... \
  ghcr.io/ni-c/freshrss-mcp:latest

Das Image wird für linux/amd64 und linux/arm64 mit einer SBOM und Build-Herkunft veröffentlicht. Es läuft als unprivilegierter node-Benutzer und enthält kein npm, sodass sich nur Node, die Laufzeitabhängigkeiten und dist/ darin befinden.

Entwicklung

npm install
npm run lint && npm run build && npm test
npm run test:coverage

Siehe CONTRIBUTING.md für eine Wegwerf-FreshRSS-Instanz zum Entwickeln. Die vollständige Dokumentation befindet sich unter freshrss-mcp.ni-c.de.

Veröffentlichung

1. Verschieben Sie die [Unreleased]-Einträge in CHANGELOG.md unter die neue Version und erhöhen Sie die version in package.json.

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

3. Committen, dann taggen: git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z.

Der Tag löst release.yml aus, das überprüft, ob der Tag mit package.json übereinstimmt, über Trusted Publishing mit Herkunftsnachweis (kein Token erforderlich) auf npm veröffentlicht, die GitHub-Version aus dem CHANGELOG-Abschnitt erstellt und den Eintrag im MCP Registry veröffentlicht. Wenn nur der Registry-Schritt fehlschlägt, beheben Sie ihn auf main und führen Sie mcp-registry.yml manuell erneut aus – führen Sie niemals den getaggten Job erneut aus, da dieser den alten Baum auschecken würde.

Lizenz

MIT