mcp-paperless-ngx

Ein MCP-Server, über den KI-Assistenten wie Claude auf Paperless-ngx zugreifen. Dokumente suchen, ablegen, verschlagworten und auswerten, ohne die Weboberfläche zu öffnen. Ich habe ihn selbst gebaut und als Open Source veröffentlicht.

Warum ich ihn gebaut habe

Der wichtigste Grund war die Tokensparsamkeit. Ein Paperless-Dokument trägt seinen kompletten OCR-Text mit sich. Reicht ein Server den ungekürzt durch, füllt schon eine Suche das Gedächtnis des Modells, und jede weitere Frage wird teurer und ungenauer. Bei den beiden aktiven Servern, die ich mir angesehen habe, habe ich kein Kürzen der Antworten gefunden. Meiner holt bei Listen nur die nötigen Felder. Den Volltext gibt es über ein eigenes Tool, seitenweise.

Der zweite Grund: Der Server unterstützt Paperless-ngx ab Version 3 vollständig und ausschließlich. Er spricht nur die API-Version 10 und nichts Älteres. Dafür nutzt er alles, was Version 3 mitbringt, zum Beispiel verschachtelte Tags, Dokumentversionen, Freigabe-Bündel und die PDF-Werkzeuge. Von den 92 dokumentierten Endpunkten ist jeder entweder als Tool vorhanden oder mit schriftlicher Begründung ausgelassen. Ein Test prüft das bei jedem Lauf. Wer noch Paperless-ngx 2 betreibt, nimmt besser einen anderen Server.

Installation

Du brauchst Node 20 oder neuer, Paperless-ngx 3 und einen API-Token.

1. API-Token holen

Klick in der Weboberfläche von Paperless oben rechts auf deinen Benutzernamen, dann auf „Mein Profil“. Neben dem Feld für den API-Token steht ein runder Pfeil. Er erzeugt den Token.

2. Verbindung prüfen

Dieser Befehl testet, ob der Server deine Instanz erreicht, und beendet sich danach:

PAPERLESS_URL=https://paperless.example.com PAPERLESS_TOKEN=dein-token npx -y mcp-paperless-ngx --check

3. In Claude Code einrichten

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=dein-token \
  -- npx -y mcp-paperless-ngx

4. In Claude Desktop, Cursor, Cline und anderen Programmen

Trag den Server in die MCP-Konfiguration des Programms ein:

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "dein-token"
      }
    }
  }
}

Starte das Programm danach neu.

Einstellungen

Alle Einstellungen laufen über Umgebungsvariablen. Nur die ersten beiden sind Pflicht.

Variable	Standard	Wofür
`PAPERLESS_URL`	keiner	Adresse deiner Paperless-Instanz
`PAPERLESS_TOKEN`	keiner	API-Token
`PAPERLESS_TOOLSETS`	siehe unten	Welche Tool-Gruppen aktiv sind, oder `all`
`PAPERLESS_READ_ONLY`	`false`	Nur Tools, die nichts verändern
`PAPERLESS_PUBLIC_URL`	wie `PAPERLESS_URL`	Adresse für Links, falls Paperless von außen anders heißt
`PAPERLESS_HEADERS`	keine	Zusätzliche Kopfzeilen, nötig hinter Forward-Auth wie Authentik oder Authelia
`PAPERLESS_DOWNLOAD_DIR`	Temp-Ordner	Wohin heruntergeladene Dateien kommen
`PAPERLESS_MAX_PAGE_SIZE`	`100`	Obergrenze für Listen, egal was das Modell verlangt

Mit --list-tools zeigt der Server, welche Tools gerade aktiv sind.

Tool-Gruppen und Kontextkosten

Standardmäßig sind sieben Gruppen aktiv: documents, metadata, customfields, views, sharing, workflows und system. Die Gruppen mail und admin sind aus, weil die meisten Sitzungen sie nie brauchen. Jedes zusätzliche Tool kostet bei jeder Anfrage Kontext:

Gruppen	Tools	Kosten pro Anfrage
alle (`all`)	99	etwa 20.500 Token
Standard	85	etwa 18.500 Token
`documents,metadata`	49	etwa 12.900 Token

Wenn du nur suchen und ablegen willst, setz PAPERLESS_TOOLSETS=documents,metadata. Das spart mehr als jede Kürzung der Antworten.

Hinter einem Anmeldeschutz

Steht vor Paperless ein Forward-Auth-Proxy, braucht der Server zusätzliche Kopfzeilen. Du gibst sie als JSON an, zum Beispiel {"X-Auth":"geheimer-wert"}.

Benutzen

Nach dem Einrichten fragst du den Assistenten in normaler Sprache. Beispiele:

„Suche alle Dokumente mit dem Tag ‚Steuer‘ aus dem letzten Jahr.“
„Welche Dokumente im Posteingang haben noch keinen Tag?“
„Fass die letzten drei Dokumente von ‚Beispiel GmbH‘ zusammen.“

Dazu gibt es drei fertige Befehle. In Programmen mit MCP-Unterstützung erscheinen sie als Slash-Befehle:

triage_inbox geht die noch nicht einsortierten Dokumente durch und schlägt Tags, Korrespondenten und Typen vor. Bestehende Einträge haben Vorrang. Angewendet wird erst nach deiner Bestätigung.
find_document sucht ein Dokument anhand einer vagen Beschreibung. Erst sucht er billig, dann breiter.
audit_sharing prüft alle öffentlichen Freigabe-Links und markiert die, die nie ablaufen.

Sicherheit

Der Server kann Dinge löschen, sonst wäre er kein brauchbarer Dokumentenverwalter. Er schützt dich an mehreren Stellen. Tools, die etwas löschen, sind als gefährlich markiert, damit dein Programm vorher nachfragen kann. Mit PAPERLESS_READ_ONLY=true verschwinden alle schreibenden Tools aus der Liste, das Modell sieht sie also gar nicht. Sammelaktionen nehmen nur ausdrückliche Listen von Dokument-Nummern, nie „alles, was auf diesen Filter passt“. Tools für Zugangsdaten, etwa neue Tokens oder die Einrichtung von TOTP, gibt es absichtlich nicht.

Ein Hinweis zu Freigaben: create_share_link erzeugt eine öffentlich erreichbare Adresse.

Die aktuelle Version

Aktuell ist Version 0.1.1 unter MIT-Lizenz. Den Quellcode gibt es auf GitHub, das Paket auf npm. Der Server steht außerdem in der offiziellen MCP-Registry. Das Projekt ist inoffiziell und nicht mit Paperless-ngx verbunden.