Konfiguration

Alle Einstellungen sind Umgebungsvariablen. Über stdio setzen Sie sie im env des Servereintrags Ihres MCP-Clients (Clients); im Fernzugriff gehören sie in die Umgebung des Servers. Nur ein Token ist Pflicht. Alles andere steht standardmäßig auf der sichersten Option: nur lesend, Bestätigung durch einen Menschen für bindende Schritte, kein Zugriff auf lokale Dateien.

Der Server liest die Variablen einmal beim Start, meldet alle Probleme auf einmal und startet erst, wenn alle behoben sind. Starten Sie nach einer Änderung den Client (oder den Server) neu.

Formate der Werte:

• Schalter nehmen 1, true, yes oder on sowie 0, false, no oder off.
• Listen sind durch Kommas getrennt, Groß- und Kleinschreibung spielt keine Rolle, zum Beispiel write,commit.
• Ordnerlisten werden wie PATH getrennt: : unter macOS und Linux, ; unter Windows. Jeder Eintrag muss ein absoluter Pfad sein.
• Ein leerer Wert gilt als nicht gesetzt. Clients, die jede Variable übergeben (wie das Claude-Code-Plugin), können die nicht benötigten leer lassen.

Variablen#

Token#

Setzen Sie genau eine dieser drei, es sei denn, das Profil, das Sie verwenden, gibt an, wo das Token liegt.

Berechtigungen#

Werkzeuge und Ausgabe#

Dateien und Audit-Log#

Im Fernzugriff liegen die Ordner auf dem Server. Der OAuth-Modus lehnt beide Ordnervariablen ab und verwendet stattdessen Seiten zum Hochladen und Download-Links (remote.de.md).

Verbindung#

Profilauswahl#

SEVDESK_PROFILE, SEVDESK_PROFILES_PATH und SEVDESK_API_TOKEN_KEYCHAIN funktionieren nur über stdio; der HTTP-Server startet mit ihnen nicht.

HTTP-Modus#

--http liest weitere Variablen (SEVDESK_HTTP_*, SEVDESK_OAUTH_*) und ändert die Bedeutung einiger der oben genannten Variablen. Beides beschreibt die Konfigurationsreferenz des Fernzugriffs.

Werkzeuggruppen#

Eine Werkzeuggruppe fasst die Werkzeuge für einen Bereich zusammen. SEVDESK_TOOLSETS wählt die Werkzeuggruppen, SEVDESK_ALLOW die Stufen darin: Ein Werkzeug wird nur angeboten, wenn beide es zulassen. Weniger Werkzeuggruppen machen die Werkzeugliste kürzer; das hilft Modellen bei der Wahl und spart Tokens.

Jedes Werkzeug mit seiner Werkzeuggruppe, Stufe und seinen Argumenten steht in der Werkzeugreferenz.

Die Werkzeuggruppe advanced#

advanced ist aus, solange Sie die Gruppe nicht nennen (SEVDESK_TOOLSETS=default,advanced) oder all laden. Sie enthält ein Werkzeug, sevdesk_api_get: ein reines Lese-GET auf einen sevDesk-Endpunkt, den kein anderes Werkzeug abdeckt, zum Beispiel die Textvorlagen (/TextTemplate), die Einheiten von Artikeln (/PartUnity) oder angehängte Dokumente (/Document).

• Es lehnt alles ab, was Daten ändern, Dateien liefern oder Hintergrundaufgaben starten könnte (getPdf, sendBy, bookAmount, enshrine, die Endpunkte für die nächste Nummer, Exporte und Berichte, …), bevor etwas gesendet wird, und es setzt nie ein Token in die URL.
• Antworten sind die rohen Objekte von sevDesk, bereinigt wie nicht vertrauenswürdiger Text: unsichtbare Zeichen entfernt, lange Zeichenketten gekürzt, Binärinhalte (Dateien in Base64, Vorschaubilder) entfernt und aufgeführt. Pro Aufruf werden höchstens etwa 100 KB zurückgegeben (Antworten über 1 MiB werden abgelehnt); nextOffset setzt eine längere Liste fort.
• Bevorzugen Sie die kuratierten Werkzeuge: Sie prüfen Eingaben, erklären Felder und formatieren Beträge und Datumsangaben.

Die Werkzeuggruppe ist standardmäßig aus, weil ein allgemeiner Lesezugriff nicht jeden Endpunkt so gut kennen kann wie ein kuratiertes Werkzeug; siehe SECURITY.de.md.

Strukturierte Ausgabe#

Jedes Werkzeug gibt sein Ergebnis als JSON-Textblock zurück. Mit strukturierter Ausgabe gibt es außerdem ein outputSchema in tools/list an und liefert dieselben Daten als typisierten structuredContent, den Clients prüfen und anzeigen können.

Grenzen#

Der Fernzugriff hat eigene Grenzen (Größe von Anfragen, Ratenbegrenzung je Client, Größe von Uploads): siehe remote.de.md.

Das Token im Schlüsselbund ablegen#

Statt das Token in die Konfiguration Ihres Clients zu schreiben, legen Sie es einmal im Schlüsselbund Ihres Betriebssystems ab und geben dem Server nur seine Bezeichnung:

npx -y mcp-server-sevdesk token set work

Der Befehl fragt nach dem Token (die Eingabe ist verdeckt), prüft es bei sevDesk, legt es unter der Bezeichnung work ab und gibt die Konto-ID aus. Lehnt sevDesk das Token ab, wird nichts abgelegt; ist sevDesk nicht erreichbar, wird es mit einer Warnung abgelegt. Konfigurieren Sie den Server dann mit "SEVDESK_API_TOKEN_KEYCHAIN": "work" statt SEVDESK_API_TOKEN.

• token check work prüft das abgelegte Token bei sevDesk; token delete work entfernt es.
• Das Token wird nie von der Kommandozeile übernommen, wo es in Ihrer Shell-Historie bliebe. Um es aus einer Datei abzulegen, leiten Sie es per Pipe ein: npx -y mcp-server-sevdesk token set work < token.txt, und löschen Sie die Datei danach.
• macOS: der Anmeldeschlüsselbund, Objekt mcp-server-sevdesk, Account = Ihre Bezeichnung.
• Linux: der Secret Service über secret-tool (Paket libsecret-tools unter Debian und Ubuntu, libsecret unter Fedora), mit laufendem und entsperrtem GNOME Keyring oder KWallet. Auf einem Server ohne grafische Oberfläche verwenden Sie SEVDESK_API_TOKEN_FILE.
• Windows: noch nicht unterstützt. Verwenden Sie SEVDESK_API_TOKEN_FILE oder die Claude-Desktop-Erweiterung, die das Token in der Anmeldeinformationsverwaltung von Windows aufbewahrt.

Der Schlüsselbund hält das Token aus Konfigurationsdateien, Backups und Screenshots heraus. Er schützt nicht vor Programmen, die bereits unter Ihrem Benutzerkonto laufen (siehe SECURITY.de.md).

Profile#

Profile halten mehrere Einrichtungen in einer Datei, zum Beispiel zwei sevDesk-Konten oder eine nur lesende und eine buchende Einrichtung desselben Kontos, und wählen eine mit SEVDESK_PROFILE aus. Legen Sie ~/.config/mcp-server-sevdesk/profiles.json an (oder zeigen Sie mit SEVDESK_PROFILES_PATH auf einen anderen Ort):

{  "version": 1,  "profiles": {    "work": {      "token": { "keychain": "work" },      "allow": ["write"],      "fileDirs": ["/Users/me/Belege"],      "auditLog": "/Users/me/.local/state/sevdesk-work.jsonl"    },    "client-a": {      "token": { "file": "/Users/me/.config/sevdesk/client-a.token" },      "readOnly": true    }  }}

Setzen Sie dann "SEVDESK_PROFILE": "work" im env des Clients. Der Server schreibt beim Start using profile "work" in sein Log.

Jeder Schlüssel setzt die Variable mit derselben Bedeutung und wird genauso geprüft. Regeln:

• Die Datei enthält nie ein Token. token sagt, wo es aufbewahrt wird: eine Bezeichnung im Schlüsselbund, ein absoluter Dateipfad oder eine Variable namens SEVDESK_TOKEN_<NAME>, die Sie im env des Clients setzen. Ohne token gelten die üblichen Token-Variablen.
• Kein stilles Überschreiben. Eine Variable, die sowohl in der Umgebung als auch im Profil gesetzt ist, ist ein Fehler, der beide nennt. Erlaubt ist nur das Verschärfen: SEVDESK_READ_ONLY=1 und SEVDESK_DRY_RUN=1 in der Umgebung haben immer Vorrang.
• Die Datei muss Ihnen gehören. Unter macOS und Linux müssen die Datei und ihr Ordner Ihnen (oder root) gehören und dürfen für Gruppe und andere nicht beschreibbar sein (chmod go-w), weil ein Profil Stufen und Ordner erweitern kann. Unter Windows wird das nicht geprüft.
• Die Datei ist striktes JSON mit höchstens 64 KiB und "version": 1; unbekannte Schlüssel werden abgelehnt.
• npx -y mcp-server-sevdesk profiles list zeigt jedes Profil mit dem Ort seines Tokens, seinen Stufen und Werkzeuggruppen und markiert das Profil, das SEVDESK_PROFILE nennt. Es gibt nie ein Token aus.
• Profile funktionieren nur über stdio, nicht mit --http.

Kommandozeile#

mcp-server-sevdesk ohne Argumente stellt MCP über stdio bereit; das führen MCP-Clients aus. Die übrigen Befehle sind für Sie. Führen Sie sie mit npx -y mcp-server-sevdesk <command> aus oder mit Docker als docker run --rm ghcr.io/jaylann/mcp-server-sevdesk:<version> <command>.

Exit-Codes: 0 Erfolg, 1 Fehlschlag (der Grund steht in stderr), 2 unbekannter Befehl oder unbekanntes Argument. Die Befehle für den Fernzugriff beschreibt remote.de.md ausführlich.

Bei einer ungültigen Konfiguration schreibt der stdio-Server die Probleme nach stderr und startet trotzdem, weil manche Clients (Claude Desktop) stderr nicht zeigen und nur „Server disconnected“ melden würden. Er bietet dann kein sevDesk-Werkzeug an, sendet nichts an sevDesk und nennt die Probleme in seinen Anweisungen und in seinem einzigen Werkzeug, sevdesk_setup_problem, damit der Assistent Ihnen sagen kann, welche Einstellung Sie korrigieren müssen. Der HTTP-Modus startet weiterhin nicht.