Configuration

All settings are environment variables. Over stdio you set them in the env of your MCP client's server entry (Clients); in remote mode they go into the server's environment. Only a token is required. Everything else defaults to the safest option: read-only, human confirmation for binding steps, no access to local files.

The server reads the variables once at startup, reports every problem at once and does not start until all of them are fixed. Restart the client (or the server) after a change.

Value formats:

• Flags take 1, true, yes or on, and 0, false, no or off.
• Lists are comma-separated and case-insensitive, for example write,commit.
• Folder lists are separated like PATH: : on macOS and Linux, ; on Windows. Every entry must be an absolute path.
• An empty value counts as unset. Clients that pass every variable (such as the Claude Code plugin) can leave the unused ones empty.

Variables#

Token#

Set exactly one of these three, unless the profile you use says where the token is kept.

Permissions#

Tools and output#

Files and the audit log#

In remote mode the folders are on the server. OAuth mode refuses both folder variables and uses upload pages and download links instead (remote.md).

Connection#

Profile selection#

SEVDESK_PROFILE, SEVDESK_PROFILES_PATH and SEVDESK_API_TOKEN_KEYCHAIN work over stdio only; the HTTP server refuses to start with them.

HTTP mode#

--http reads further variables (SEVDESK_HTTP_*, SEVDESK_OAUTH_*) and changes the meaning of some of the variables above. Both are described in the remote mode configuration reference.

Toolsets#

A toolset is a group of tools for one area. SEVDESK_TOOLSETS picks the toolsets, and SEVDESK_ALLOW picks the tiers within them: a tool is offered only when both enable it. Loading fewer toolsets makes the tool list shorter, which helps models choose and saves tokens.

Every tool, with its toolset, tier and arguments, is listed in the tool reference.

The advanced toolset#

advanced is off unless you name it (SEVDESK_TOOLSETS=default,advanced) or load all. It has one tool, sevdesk_api_get: a read-only GET of a sevDesk endpoint that no other tool covers, for example the text templates (/TextTemplate), units of parts (/PartUnity) or attached documents (/Document).

• It refuses everything that could change data, return files or start jobs (getPdf, sendBy, bookAmount, enshrine, the next-number endpoints, exports and reports, …) before anything is sent, and it never puts a token into the URL.
• Answers are sevDesk's raw objects, cleaned as untrusted text: invisible characters removed, long strings cut, binary content (base64 files, thumbnails) removed and listed. At most about 100 KB are returned per call (answers over 1 MiB are refused); nextOffset continues a longer list.
• Prefer the curated tools: they check inputs, explain fields and format money and dates.

The toolset is off by default because a generic read cannot know every endpoint as well as a curated tool; see SECURITY.md.

Structured output#

Every tool returns its result as a JSON text block. With structured output it also declares an outputSchema in tools/list and returns the same data as typed structuredContent, which clients can validate and display.

Limits#

Remote mode adds limits of its own (body sizes, rate limits per client, upload sizes): see remote.md.

Keep the token in the OS keychain#

Instead of writing the token into your client's configuration, store it once in your operating system's keychain and give the server only its label:

npx -y mcp-server-sevdesk token set work

The command asks for the token (the input is hidden), checks it with sevDesk, stores it under the label work and prints the account id. If sevDesk rejects the token, nothing is stored; if sevDesk cannot be reached, it is stored with a warning. Then configure the server with "SEVDESK_API_TOKEN_KEYCHAIN": "work" instead of SEVDESK_API_TOKEN.

• token check work checks the stored token with sevDesk; token delete work removes it.
• The token is never taken from the command line, where it would stay in your shell history. To store it from a file, pipe it in: npx -y mcp-server-sevdesk token set work < token.txt, then delete the file.
• macOS: the login keychain, item mcp-server-sevdesk, account = your label.
• Linux: the Secret Service through secret-tool (package libsecret-tools on Debian and Ubuntu, libsecret on Fedora), with GNOME Keyring or KWallet running and unlocked. On a headless server, use SEVDESK_API_TOKEN_FILE.
• Windows: not supported yet. Use SEVDESK_API_TOKEN_FILE, or the Claude Desktop extension, which keeps the token in Windows' credential storage.

The keychain keeps the token out of configuration files, backups and screenshots. It does not protect against programs that already run under your user account (see SECURITY.md).

Profiles#

Profiles keep several setups in one file, for example two sevDesk accounts, or a read-only and a bookkeeping setup of the same account, and pick one with SEVDESK_PROFILE. Create ~/.config/mcp-server-sevdesk/profiles.json (or point SEVDESK_PROFILES_PATH elsewhere):

{  "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    }  }}

Then set "SEVDESK_PROFILE": "work" in the client's env. The server logs using profile "work" at startup.

Each key sets the variable of the same meaning and is checked the same way. Rules:

• The file never holds a token. token says where it is kept: a keychain label, an absolute file path, or a variable named SEVDESK_TOKEN_<NAME> that you set in the client's env. Without token, the usual token variables apply.
• No silent overrides. A variable set both in the environment and by the profile is an error that names both. Only tightening is allowed: SEVDESK_READ_ONLY=1 and SEVDESK_DRY_RUN=1 in the environment always win.
• The file must be yours. On macOS and Linux the file and its folder must belong to you (or root) and must not be writable by group or others (chmod go-w), because a profile can widen tiers and folders. Windows does not check this.
• The file is strict JSON of at most 64 KiB with "version": 1; unknown keys are refused.
• npx -y mcp-server-sevdesk profiles list shows every profile with where its token is kept, its tiers and toolsets, and marks the one SEVDESK_PROFILE names. It never prints a token.
• Profiles work over stdio only, not with --http.

Command line#

mcp-server-sevdesk without arguments serves MCP over stdio; that is what MCP clients run. The other commands are for you. Run them with npx -y mcp-server-sevdesk <command>, or with Docker as docker run --rm ghcr.io/jaylann/mcp-server-sevdesk:<version> <command>.

Exit codes: 0 success, 1 failure (the reason is printed to stderr), 2 unknown command or argument. The remote-mode commands are described in detail in remote.md.

With an invalid configuration the stdio server prints the problems to stderr and still starts, because some clients (Claude Desktop) hide stderr and would only report "Server disconnected". It then offers no sevDesk tool, sends nothing to sevDesk, and names the problems in its instructions and in its one tool, sevdesk_setup_problem, so the assistant can tell you which setting to fix. The HTTP mode still refuses to start.