mcp-paperless-ngx

Entwickelt für die REST-API Version 10, mit drei Dingen, die es anders macht:

• Lückenlose Abdeckung. Jeder der 92 dokumentierten Endpunkte ist entweder als Tool verfügbar oder in src/tools/coverage.ts mit einer schriftlichen Begründung für den Ausschluss gelistet. Ein Test erzwingt das, sodass ein Paperless-Release, das einen Endpunkt hinzufügt, in der CI fehlschlägt, anstatt stillschweigend nicht unterstützt zu werden.

• Token-Disziplin. Ein Paperless-Dokument enthält seinen vollständigen OCR-Text. Naive Wrapper geben ihn standardmäßig zurück, und eine einzige Suche kann den Kontext des Modells erschöpfen. Hier werden Listenergebnisse serverseitig über ?fields= beschnitten, der Text liegt hinter einem eigenen paginierten Tool, und kein Listen-Endpunkt reicht die rohe API-Antwort durch — ein Test erzwingt das. Siehe Kontextkosten.

• Begrenzte Oberfläche. 99 Tools würden die Tool-Liste eines Modells überfluten. Toolsets ermöglichen es, nur das freizugeben, was ein bestimmter Client benötigt, und --read-only entfernt sämtliche Schreibpfade vollständig.

Paperless-ngx 2.x wird nicht unterstützt: API-Version 10 führte Endpunkte ein (verschachtelte Tags, Dokumentversionen, share_link_bundles, die Split-PDF-Operationen), die dieser Server voraussetzt.

Schnellstart

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

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

Claude Desktop, Cursor, Cline und andere MCP-Clients

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

API-Token erhalten

Paperless-Web-UI → Ihr Benutzername (oben rechts) → Mein Profil → die kreisförmige Pfeil-Schaltfläche neben dem API-Token-Feld.

Related MCP server: paperlessngx-mcp

Konfiguration

Die CLI-Flags --url, --token, --public-url, --toolsets und --read-only haben Vorrang vor der Umgebung. --check prüft die Verbindung, --list-tools gibt die aktivierten Tools aus.

Toolsets

mail und admin sind standardmäßig deaktiviert, weil die meisten Sitzungen sie nie benötigen und jedes zusätzliche Tool bei jeder Anfrage Kontext kostet. Aktivieren Sie sie explizit:

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

Kontextkosten

Eine API für ein Sprachmodell zu kapseln, hat Kosten, die die API selbst nicht hat: Alles, was das Modell sieht, wird bei jeder Anfrage bezahlt. Zwei Stellen, an denen das zuschlägt, und was dieser Server dagegen tut.

Antworten. Drei Antwortformen sind in Paperless teuer und werden leicht versehentlich zurückgegeben:

Tool-Definitionen. Das sind die größeren und weniger offensichtlichen Kosten: Namen, Beschreibungen und JSON-Schemata werden mit jeder Anfrage mitgeschickt, ob nun ein Tool aufgerufen wird oder nicht.

Es gibt keinen Weg, das kostenlos zu machen — es ist der Preis für ein Tool, das das Modell ohne Raten nutzen kann. Aber es lohnt sich, bewusst zu wählen: Wenn Ihre Sitzungen nur Dokumente suchen und ablegen, spart das Ausführen von PAPERLESS_TOOLSETS=documents,metadata mehr Kontext als jede Antwortkürzung.

Sicherheit

Der Server stellt destruktive Operationen bereit, denn ein Dokumentenmanager ohne sie ist kein großer Manager. Er versucht nicht zu erraten, wann sie angemessen sind — dieses Urteil obliegt dem Client und dem Benutzer. Was er stattdessen tut:

• Destruktive Tools sind mit destructiveHint: true annotiert, sodass MCP-Clients eine Bestätigung verlangen können.

• Die Tool-Beschreibungen sagen deutlich, was nicht rückgängig gemacht werden kann (empty_trash, delete_custom_field, delete_originals), und bitten vor dem Aufruf um Bestätigung.

• --read-only entfernt alle Schreib-Tools aus der Liste, anstatt sie erst beim Aufruf abzulehnen.

• Bulk-Endpunkte unterstützen einen Modus „Auf alles anwenden, was diesem Filter entspricht“. Dieser Server legt ihn nicht offen: Bulk-Tools akzeptieren explizite ID-Listen, sodass ein falscher Filter nicht stillschweigend das gesamte Archiv beeinflussen kann.

• create_share_link erzeugt eine öffentlich erreichbare URL. Die Beschreibung sagt das, und der Prompt audit_sharing dient dazu, zu prüfen, was bereits offengelegt ist.

Endpunkte mit Bezug zu Anmeldedaten (Token-Erzeugung, TOTP-Registrierung, Deaktivieren des zweiten Faktors einer Person) werden bewusst nicht offengelegt. Die vollständige Liste und die Begründung finden Sie unter EXCLUDED_ENDPOINTS.

Prompts

In Clients, die MCP-Prompts unterstützen, sind sie als Slash-Befehle registriert:

Tests

Drei Ebenen, weil sie unterschiedliche Dinge abdecken:

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test prüft die eigene Logik dieses Servers: Endpunktabdeckung, Enum-Werte gegen das Schema, dass kein Listen-Tool rohe API-Objekte durchlässt, dass der Nur-Lese-Modus Schreibzugriffe wirklich entfernt.

smoke-test.mjs prüft die Annahmen, die es über Paperless trifft. Es ruft jedes Nur-Lese-Tool gegen eine echte Instanz auf, löst IDs aus Listenaufrufen auf, statt sie fest zu kodieren, und gibt Antwortgrößen aus, damit teure Tools sichtbar bleiben. Es schreibt nichts.

write-test.mjs deckt den Rest ab: Upload und Verarbeitung, Aktualisieren jedes Feldtyps, Notizen, Bulk-Tag-Bearbeitungen, Freigabe-Links, Rotation und einen Papierkorb-Durchlauf.

Es berührt nur Objekte, die es selbst erstellt. Alles, was es erzeugt, trägt ein zz-mcp-test-Präfix und wird am Ende wieder gelöscht, und es verändert nie ein Dokument, das es nicht hochgeladen hat. Wenn ein Lauf unterbrochen wird, können Rückstände mit diesem Präfix bedenkenlos gelöscht werden. Bevorzugen Sie eine Testinstanz, falls Sie eine haben.

Mit Paperless Schritt halten

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs regeneriert schema/endpoints.json aus dem OpenAPI-Dokument Ihrer eigenen Instanz. Die Testsuite meldet dann jeden Endpunkt, der weder verfügbar gemacht noch explizit ausgeschlossen ist. Das ist der gesamte Wartungszyklus: Richten Sie es auf ein neueres Paperless aus, und der Test sagt Ihnen, was sich geändert hat.

Entwicklung

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

Vorarbeiten

Mehrere MCP-Server für Paperless existieren bereits, insbesondere cubite-code/paperless-ngx-mcp, sowie nloui/paperless-mcp und barryw/PaperlessMCP. Diese zielen auf die 2.x-API ab. Wenn du Paperless-ngx 2.x verwendest, nutze einen davon; dieser hier setzt 3.x voraus.

Lizenz

MIT. Siehe LIZENZ.