fileee-mcp-server

Ein inoffizieller MCP-Server für Fileee, der die eigenen Dokumente für AI-Clients zugänglich macht — als lokaler Server über einen statischen Token oder als Remote-Connector mit OAuth-Anmeldung, etwa in der Claude.ai-Web-UI.

Stand: Das Grundgerüst steht — Konfiguration, Anmeldung über Gangway, Zuordnung von Identität zu Fileee-Konto. Die lesenden UND die schreibenden Werkzeuge sind vollständig angemeldet: 32 lesende plus 8 schreibende fileee-Werkzeuge (siehe docs/tools.md) plus 4 Betriebswerkzeuge (get_runtime_stats, get_tool_manifest, self_check, whoami) — 44 Werkzeuge insgesamt. Teilende und löschende Werkzeuge entstehen weiterhin in den folgenden Umsetzungsschritten.

Der Server nutzt die Core-Lib strausmann/go-fileee und ist damit Geschwisterprojekt von strausmann/fileee-server (REST-API für n8n/CI). Der Unterschied: fileee-server kennt genau ein Fileee-Konto und ein statisches Token; dieser Server bindet die Identität des anfragenden Benutzers an ein Fileee-Konto.

Dieses Projekt ist ein unabhängiges Community-Projekt und steht in keiner Verbindung zur fileee GmbH.

Was es kann

• MCP über Streamable HTTP (POST /mcp), auf Basis des offiziellen Go-SDK

• OAuth 2.1 als Resource Server nach RFC 9728 — der Identity Provider ist frei wählbar und reine Konfiguration

• Statisches Bearer-Token als Alternative, wenn kein IdP vorhanden ist

• Ein oder mehrere Fileee-Konten, zugeordnet über einen signierten Claim aus dem Token

• Alle Werkzeuge angemeldet, Freigabe je Werkzeug beim Client — jedes Werkzeug trägt einen Titel und die zutreffenden ToolAnnotations (readOnlyHint, destructiveHint, idempotentHint); Always allow / Needs approval / Blocked entscheidet der Client und dessen Benutzer, nicht der Server (siehe ADR-0018)

Related MCP server: paperless-mcp

Drei Betriebsarten

Derselbe Container bedient sehr verschiedene Setups. Die drei Achsen sind unabhängig voneinander schaltbar.

Eine Person, ein Fileee-Konto, kein Identity Provider

MCP_AUTH_MODE=token
MCP_API_TOKEN=<openssl rand -hex 32>
FILEEE_MODE=single
FILEEE_USERNAME=…
FILEEE_PASSWORD=…
FILEEE_TOTP_SEED=…        # nur bei aktiver Zwei-Faktor-Authentifizierung

Drei Pflichtwerte, kein IdP, kein Reverse Proxy nötig. Für Claude Code lokal oder für Automatisierung im eigenen Netz.

Remote-Connector mit OAuth

MCP_OIDC_PROVIDER wählt den Identity Provider. Jeder Anbieter hat seinen eigenen Satz Variablen — du trägst ein, was dein Anbieter dir zeigt, und der Server baut die Aussteller-URL daraus (siehe ADR-0016):

Variablen eines anderen als des gewählten Anbieters lassen den Start abbrechen — sie wären sonst wirkungslos gesetzt.

MCP_AUTH_MODE=oidc
MCP_OIDC_PROVIDER=entra
MCP_ENTRA_TENANT_ID=<verzeichnis-id>
MCP_ENTRA_CLIENT_ID=<anwendungs-id>
MCP_RESOURCE_URL=https://<mcp-host>/mcp
MCP_ALLOWED_SUBJECTS=<subject des berechtigten Benutzers>
FILEEE_ALLOWED_ORIGIN_PREFIXES=<CIDR-Liste der zulässigen Herkunftsadressen>
FILEEE_MODE=single

Einrichtung des Identity Providers — eine Anleitung je Anbieter, jede nur mit ihren eigenen Variablen:

Danach in allen Fällen: docs/idp/claude-connector.md.

Aktuell nur oidc. Der Server läuft auf Gangway (siehe ADR-0015) auf, und Gangway v0.2.0 baut intern ausschließlich einen OIDC-Verifier — es gibt (noch) keinen Weg, stattdessen ein statisches Bearer-Token zu verifizieren. MCP_AUTH_MODE=token/both werden von LoadConfig weiterhin akzeptiert, der Server verweigert den Start mit diesem Modus aber explizit. Details und der Ausblick auf eine Lösung stehen im Nachtrag zu ADR-0015.

Weitere netzwerkbezogene Variablen, die im Modus oidc Pflicht bzw. relevant sind:

Zwei weitere Variablen rund um Scopes — angefordert/geprüft und angekündigt sind bei den meisten Anbietern derselbe Wert, aber nicht bei jedem:

Der Grund für die Trennung: ein Connector, der noch kein Token besitzt, erfährt den geforderten Scope ausschließlich über diese Ankündigung. Bei den meisten Anbietern (u. a. Authentik) ist der beim Anbieter angeforderte Scope-Name identisch mit dem später im Token ausgestellten scp-Wert — MCP_OIDC_REQUIRED_SCOPES allein reicht. Microsoft Entra ID ist die dokumentierte Ausnahme: angekündigt/angefordert werden muss dort eine vollqualifizierte Form (https://<mcp-host>/mcp/<scope-name>), während der ausgestellte scp-Claim weiterhin nur den kurzen Namen trägt — ein nackter Name scheitert beim Anbieter mit AADSTS650053. Details zur Entra-spezifischen Form: docs/idp/entra-id.md.

Mehrere Benutzer, je eigenes Fileee-Konto

MCP_AUTH_MODE=oidc
FILEEE_MODE=multi
FILEEE_ACCOUNTS=alice,bob
FILEEE_ACCOUNT_ALICE_USERNAME=…
FILEEE_ACCOUNT_ALICE_PASSWORD=…
FILEEE_ACCOUNT_ALICE_SUBJECTS=alice@example.com
FILEEE_ACCOUNT_BOB_USERNAME=…
…

Die Zuordnung läuft über einen konfigurierbaren Claim aus dem Token (Default sub). Mehrere Identitäten dürfen auf ein Fileee-Konto zeigen; eine Identität auf zwei Konten ist ein Startup-Fehler, kein „first match wins". Ein unbekanntes Subject bekommt 403 — es gibt keinen Fallback auf ein Standardkonto.

Mehrere Instanzen unterscheiden

Laufen mehrere Instanzen dieses Servers gegen verschiedene Fileee-Konten und sind beide gleichzeitig in einem Client eingebunden, hilft MCP_INSTANCE_DESCRIPTION (optional, höchstens 2000 Zeichen) dabei, sie auseinanderzuhalten:

MCP_INSTANCE_DESCRIPTION="Testumgebung. Wegwerfdaten, hier darf experimentiert werden. Nicht das produktive Archiv."

Das ist ein Wegweiser, keine Schranke — durchgesetzt wird die Trennung durch getrennte Fileee-Zugangsdaten je Instanz, durch die client-seitige Werkzeug-Freigabe und durch die ID-Whitelist. Details und bewährte Formulierungen: docs/betrieb/aufbau.md, Abschnitt „Mehrere Instanzen unterscheiden".

Funktionsumfang

Der Server registriert alle Werkzeuge für jeden authentifizierten Aufrufer — es gibt keine serverseitige Einschränkung mehr, welche Werkzeuge ein Client zu sehen bekommt (siehe ADR-0018). Jedes Werkzeug trägt einen sprechenden Titel und die zutreffenden Hinweise (readOnlyHint, destructiveHint, idempotentHint) — die Freigabe je Werkzeug (Always allow / Needs approval / Blocked) trifft der Client und dessen Benutzer, nicht der Server.

Destruktive Operationen (Hard-DELETE, unwiderruflich, kein Papierkorb) sind zusätzlich über ein serverseitiges Audit-Log vor jeder Löschung abgesichert und daran gebunden, dass die zu löschende ID aus einer vorangegangenen Leseantwort derselben geprüften Identität stammt — gebunden an serve.IdentityFrom(ctx), nicht an die MCP-Sitzung, die es unter der erzwungenen Statelessness ohnehin nicht über den einzelnen Request hinaus gibt.

Werkzeuge

Der Katalog entsteht schrittweise. Die lesenden Werkzeuge sind vollständig angemeldet — 32 Werkzeuge über Dokumente, Stammdaten (Schlagworte, Firmen, Dokumenttypen, Dokumenttyp-Schemata), Kontakte/Erinnerungen/Konversationen, Boxen, PDF-/Seitenbild-Download mit harter Größenobergrenze, Seiten-OCR und Kontostand — vollständig in docs/tools.md dokumentiert, inklusive der Absicherung gegen präparierte, fremdbestimmte Inhalte (Dokumenttitel, Firmen-/ Kontaktnamen, Erinnerungstexte, Konversationsbetreffs, erkannter OCR-Text).

Die schreibenden Werkzeuge sind ebenfalls vollständig angemeldet — 8 Werkzeuge über Kontakte (create_contact/update_contact), Erinnerungen (create_reminder/update_reminder), Boxen (box_add_document/box_remove_document) und Dokumente (upload_document/update_document), jedes mit wahrheitsgemäßen ToolAnnotations (destructiveHint, idempotentHint) — ebenfalls vollständig in docs/tools.md dokumentiert, im Abschnitt „write — schreibende Werkzeuge".

Teilende und löschende Werkzeuge entstehen weiterhin in den folgenden Umsetzungsschritten — jedes davon wird, sobald es existiert, ebenso angemeldet und über seine ToolAnnotations beschrieben (siehe ADR-0018).

Sicherheit

• Credentials (Fileee-Zugangsdaten, TOTP-Seed, API-Token) gehören ausschließlich in einen Secret-Manager, nie in Code oder Commits. Der Container unterstützt neben .env einen Infisical-Modus: Sind INFISICAL_UNIVERSAL_AUTH_CLIENT_ID und INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET (oder INFISICAL_TOKEN) gesetzt, meldet sich der Entrypoint an und injiziert die Werte; sonst startet der Server direkt mit den vorhandenen Umgebungsvariablen. Ist nur eine der beiden Variablen gesetzt, bricht der Start ab — ein halbes Paar ist nie Absicht, und ein stiller Rückfall auf den Umgebungs-Weg würde den Fehler erst viel später sichtbar machen.

• Session-Dateien des Client-Pools sind Secrets (0600, je Konto getrennt) und werden nie geloggt.

• Dokumentinhalte sind fremdbestimmte Daten. OCR-Text kann Anweisungen enthalten, die an das Modell gerichtet sind. Tool-Ausgaben werden deshalb als nicht vertrauenswürdig markiert, und destruktive Operationen sind zusätzlich abgesichert.

• Die Core-Lib schont Fileees Infrastruktur über ihr eigenes Rate-Limiting und Backoff im HTTP-Transport (go-fileee ADR-0005). Dieser Server ergänzt eine zweite, unabhängige Begrenzung auf Ebene der Werkzeugaufrufe selbst — siehe „Ratenbegrenzung" unten.

Ratenbegrenzung

Jeder Aufruf eines Werkzeugs (tools/call) muss drei unabhängige Kontingente passieren, bevor er den Tool-Handler überhaupt erreicht — ein Aufrufer, der eines davon überschreitet, bekommt sofort einen JSON-RPC-Fehler (Code -32011), nie eine Wartezeit:

FILEEE_MAX_UPLOAD_BYTES wird von upload_document durchgesetzt (internal/tools/write_documents.go, uploadDocumentHandler): Der Aufruf wird abgelehnt, bevor irgendetwas dekodiert wird, sobald allein die Länge der base64-kodierten contentBase64-Zeichenkette beweist, dass der dekodierte Inhalt das Limit überschreiten müsste — und ein zweites Mal auf der tatsächlichen dekodierten Bytezahl, falls die erste, konservative Prüfung eine Eingabe durchlässt, die sich erst nach dem Dekodieren als zu groß herausstellt. Ein Wert von 0 bedeutet dabei nicht „unbegrenzt", sondern wird wie jede andere Obergrenze durchgesetzt (lehnt jeden nicht-leeren Upload ab) — dieselbe Konvention, die FILEEE_MAX_INFLIGHT bei 0 bereits hat (siehe „Ratenbegrenzung" oben).

FILEEE_MAX_DOWNLOAD_BYTES wird ebenfalls geladen, ist aber nicht mit den beiden inzwischen existierenden Download-Werkzeugen verbunden: get_document_pdf und get_page_image (siehe docs/tools.md) begrenzen ihren jeweiligen Datenstrom über eine eigene, im Code fest verdrahtete Obergrenze von 8 MiB (maxBinaryBytes, internal/tools/read_binary.go), unabhängig vom konfigurierten Wert dieser Variable (Default 1 MiB) — wer FILEEE_MAX_DOWNLOAD_BYTES setzt, ändert damit nichts am tatsächlichen Verhalten dieser beiden Werkzeuge. Das ist eine offene Inkonsistenz, keine bewusste Entscheidung; bis sie aufgelöst ist (entweder maxBinaryBytes auf cfg.MaxDownloadBytes umstellen oder die Variable als für diese Werkzeuge nicht zuständig dokumentieren), gilt für einen Betreiber: die tatsächliche Grenze ist die feste 8-MiB-Konstante im Code, nicht FILEEE_MAX_DOWNLOAD_BYTES.

Die von FILEEE_MAX_UPLOAD_BYTES abgeleitete MaxRequestBodyBytes bleibt aus einem unabhängigen Grund offen: Gangway v0.2.0 baut den HTTP-Handler intern ohne einen Weg, dessen Größenlimit zu überschreiben (siehe ADR-0015).

ID-Whitelist für destruktive Operationen

Wichtiger Stand für dieses Increment, vorab: internal/server.New baut aus beiden Werten den internal/issued.Store. Die eine Hälfte ist bereits verdrahtet — aber seit einem Sicherheits-Audit (2026-08-25, ADR-0019 „Nachtrag") mit einer bewusst engen Erfassungslinie, NICHT mehr „jeder erfolgreiche Lese-Aufruf": NUR gezielte Einzelabrufe — ein Werkzeug, dem der Aufrufer EINE ID im Parameter nennt und das GENAU DIESE eine, vom Server bestätigte Entität zurückgibt — ruft rec.Record. Das sind get_document, get_box, get_document_pdf und der generische Einzelabruf-Pfad hinter registerReferenceTools/registerPeopleTools (getFromService, jeweils nur die per id-Parameter angeforderte ID, NICHT zusätzliche Nebenprodukt-IDs wie get_documents TagIDs oder get_boxs DocumentIDs). get_document_pdf gehört seit einer Korrektur (Codex-Review-Fund an PR #75, 2026-08-25) ebenfalls dazu: es ist genau so ein gezielter Einzelabruf — der Aufrufer nennt EINE ID, der Server bestätigt sie als existierend und lesbar, indem er das PDF erfolgreich lädt —, nur reist die ID dabei nicht in StructuredContent, sondern eingebettet in die Resource-URI des zurückgegebenen mcp.EmbeddedResource (siehe internal/tools/read_binary.gos eigenen WICHTIG-Kommentarblock). Die übrigen handgeschriebenen Werkzeuge — list_documents, search_documents, sync_documents, list_document_conversations, list_boxes — sowie alle generischen Listen-/Sync-Werkzeuge (registerSyncTools) nehmen SEIT DIESEM AUDIT KEINE ID mehr auf: sie liefern mehrere Entitäten zurück, ohne dass der Aufrufer eine davon einzeln genannt hätte, was die Erfassung sonst fast wertlos macht (ein einziger list_documents-Aufruf hätte bis zu 100 IDs aufgenommen, sync_documents beim ersten Aufruf gleich den gesamten Bestand, list_boxes/get_box waren zuvor ungedeckelt) — siehe ADR-0019s „Nachtrag" für die volle Begründung, den bewusst gezahlten Preis (ein zusätzlicher Einzelabruf pro ID) und was der Mechanismus weiterhin nicht leistet. get_page_image/get_page_ocr nehmen dagegen weiterhin nie eine ID auf (siehe deren eigene Doc-Kommentare — get_page_image gibt seine pageId in keiner Form an den Aufrufer zurück, und kein Schreib-Werkzeug dieses Servers akzeptiert überhaupt eine Seiten-ID als Parameter). FILEEE_ISSUED_ID_TTL_SECONDS und FILEEE_ISSUED_ID_MAX_PER_IDENTITY greifen dabei bereits produktiv — FILEEE_ISSUED_ID_MAX_PER_IDENTITY=0 etwa sorgt dafür, dass sich der Store tatsächlich nichts merkt, weil jede Aufnahme sofort verdrängt wird. Noch nicht verdrahtet ist die Gegenseite: Kein Werkzeug befragt eine übergebene ID vor dem Handeln über rec.Check gegen diesen Store — das ist der Schritt, den ein späteres Increment (Spec 3b, destruktive und share-Werkzeuge, siehe ADR-0013/ADR-0019) nachträgt. Bis dahin hat das Aufnehmen selbst noch keine schützende Wirkung; es legt nur die Grundlage, gegen die eine künftige Prüfung greifen kann.

Beide Werte steuern internal/issued.Store (ADR-0013 Punkt 3): Sobald ein Werkzeug ihn befragt, darf eine Identität ein destruktives Werkzeug nur auf eine ID anwenden, die ein vorheriges Lese-Werkzeug für dieselbe Identität tatsächlich ausgeliefert hat — eine ID, die nur im Text eines fremden Dokuments auftaucht (etwa in einem eingebetteten Prompt-Injection-Versuch), wäre nie Teil dieser Merkliste und würde deshalb abgelehnt. Innerhalb des Stores sind beide Grenzen bereits jetzt tatsächlich durchgesetzt, nicht nur geladen — derselbe Fehler, den FILEEE_MAX_UPLOAD_BYTES vor dem write-tools-Increment hatte (siehe oben): eine Einstellung ohne Aufrufstelle täuscht Sicherheit vor, die nicht besteht.

Ein Wert von 0 bedeutet bei beiden nicht „unbegrenzt", sondern wird als reale Grenze durchgesetzt (FILEEE_ISSUED_ID_TTL_SECONDS=0: jede ID gilt sofort als verfallen; FILEEE_ISSUED_ID_MAX_PER_IDENTITY=0: es wird sich nichts gemerkt) — dieselbe fail-closed-Konvention wie bei FILEEE_MAX_INFLIGHT/FILEEE_MAX_UPLOAD_BYTES oben. Negative Werte lehnt der Start mit einer Fehlermeldung ab.

Diagnose

FILEEE_LOG_LEVEL steuert das diagnostische Protokoll dieses Servers (internal/diag) — ein JSON-Objekt pro Zeile auf der Standardausgabe, unabhängig von Gangways eigenem Zugriffsprotokoll (NGINX-Format, siehe dessen Doku) und von den Start-/Fehlermeldungen in cmd/fileee-mcp-server/main.go, die weiterhin unverändert auf stdout/stderr laufen.

FILEEE_LOG_LEVEL=info     # Default
FILEEE_LOG_LEVEL=debug

Niemals, auf keiner Stufe: Zugangsdaten, Token, TOTP-Seed, Antwortkörper der Fileee-API, Dokumentinhalte oder -titel. Jedes Attribut, das dieser Logger schreibt — unabhängig davon, welcher Code es erzeugt hat, unabhängig von der Stufe — läuft durch eine einzige Maskierung (internal/diag, redactingHandler): ein Feldname, der wie ein Credential aussieht (password, secret, token, totp, seed, authorization, apikey, credential, cookie, als Teilstring, unabhängig von Groß-/Kleinschreibung), wird durch *** ersetzt, bevor er die Ausgabe erreicht — auch verschachtelt in einer Argument-Gruppe.

debug enthält Suchbegriffe (das Argument von search_documents) und ist damit selbst schon eine — wenn auch begrenzte — inhaltliche Angabe über die Dokumente des aufrufenden Kontos. Für den Dauerbetrieb ist info vorgesehen; debug ist ein befristetes Werkzeug zum Fehlersuchen, keine Dauereinstellung.

Entwicklung

go build ./...
go vet ./...
go test ./... -race -count=1
gofmt -l .                                  # muss leer bleiben
./scripts/coverage-gate-strict.sh cover.out …
./scripts/doc-coverage.sh

Voraussetzung: Go 1.25 oder neuer. Neuer Code folgt strikt TDD — erst ein fehlschlagender Test, dann die Implementierung. Details in CONTRIBUTING.md, Architekturentscheidungen in docs/adr/.

Disclaimer

Fileee bietet kein offizielles API. Die zugrunde liegende Core-Lib rekonstruiert das interne Protokoll der Web-App. Konsequenzen:

• Fileee kann das interne API jederzeit ohne Ankündigung ändern — dieser Server kann dadurch brechen.

• Die Nutzung ist für eigene Fileee-Konten vorgesehen, nicht für fremde Konten oder Massenzugriffe.

• Es gibt keine Gewähr für Vollständigkeit, Korrektheit oder Dauerhaftigkeit der Funktionalität.

• Nutzer sind selbst dafür verantwortlich, die Nutzungsbedingungen von Fileee einzuhalten.

Lizenz

MIT — Copyright © 2026 Björn Strausmann