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 Capability-Gruppe read ist vollständig: 32 lesende Werkzeuge, siehe docs/tools.md. Die Capability-Gruppen write, share und destructive entstehen 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

• Konfigurierbarer Funktionsumfang über Capability-Gruppen — nicht freigeschaltete Tools werden gar nicht erst registriert

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
FILEEE_CAPABILITIES=read

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_ALICE_CAPABILITIES=read
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.

Funktionsumfang festlegen

FILEEE_CAPABILITIES=read                              # Default
FILEEE_CAPABILITIES=read,write
FILEEE_CAPABILITIES=read,write,share
FILEEE_CAPABILITIES=read,write,share,destructive      # zusätzlich FILEEE_ALLOW_DESTRUCTIVE=true

Nicht freigeschaltete Tools werden dem Client gar nicht erst angeboten.

Wer wie viel darf

Der Umfang kann aus drei Quellen kommen. Es gilt eine feste Rangfolge, keine Vermischung:

1. FILEEE_CAPABILITIES ist die Obergrenze. Keine andere Quelle schaltet darüber hinaus etwas frei.

2. Der Identity Provider entscheidet, sofern MCP_OIDC_CAPABILITY_CLAIM gesetzt ist — Entra über App-Rollen (roles), Authentik über Gruppen (groups). Damit werden Berechtigungen dort gepflegt, wo Benutzer ohnehin verwaltet werden. Für die meisten Setups genügen zwei Stufen: read und write.

3. Sonst gilt FILEEE_ACCOUNT_<KEY>_CAPABILITIES, sonst die Obergrenze.

Ist der Claim konfiguriert, der Benutzer hat aber keine passende Rolle oder Gruppe, bekommt er read — nicht den konfigurierten Standardumfang. Andernfalls wäre eine vergessene Zuweisung eine stille Rechteausweitung.

destructive ist über keinen Claim erreichbar und bleibt eine bewusste Entscheidung am Server.

Fileees Hard-DELETE ist unwiderruflich und kennt keinen Papierkorb. Deshalb die zwei Schalter, ein Audit-Log vor jeder Löschung und die Regel, dass eine zu löschende ID aus einer vorangegangenen Leseantwort derselben geprüften Identität stammen muss — 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 Capability-Gruppe read ist vollständig — 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). write, share und destructive entstehen in den folgenden Umsetzungsschritten.

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 geladen, aber noch nicht durchgesetzt — es gibt noch kein Upload-Werkzeug (Teil B, write), das es aufrufen könnte.

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).

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