@kontor-mcp/server

Sovereign MCP server for German/EU e-invoices (XRechnung, ZUGFeRD/Factur-X, EN 16931): parse, validate and explain — 100 % offline, no Java, no network.

Tools (v0.9)

| Tool | Purpose | |---|---| | parse_invoice | Detect format (UBL/CII · EN 16931 · XRechnung version/variant · ZUGFeRD profile) and return the EN 16931 semantic model | | validate_invoice | XSD + official EN 16931 / XRechnung Schematron with the KoSIT scenario model → valid / valid_with_warnings / invalid, findings with DE/EN explanations and fix hints | | audit_invoice | One call for AP: parse + validate + Kontor plausibility (totals recomputed, VAT rates, IBAN, Leitweg-ID check digits, dates, known_invoice_numbers duplicates) → header facts, VAT breakdown, verdict, grouped findings, accept / review / reject with rationale | | generate_invoice | Structured data → compliant XRechnung 3.0 (UBL) or, with target: zugferd-pdf, a ZUGFeRD 2.3 / Factur-X PDF/A-3 (zugferd_profile EN16931 / BASIC / EXTENDED, embedded factur-x.xml, veraPDF- and Mustang-verified): decimal-safe amounts/VAT/totals, internal validation (fail-honest valid — for PDFs the XML is read back out of the file first), deterministic auto-fixes reported, optional output_path (.xml / .pdf, never overwrites unless overwrite=true), otherwise pdf_base64 | | convert_invoice | extract-xml (ZUGFeRD PDF → XML), xrechnung-ubl / cii via the semantic model with post-validation and an honest lossReport, html-preview (self-contained HTML, no scripts/assets); optional output_path | | check_obligations | Offline decision tree over the German mandate (§ 14 / § 27 Abs. 38 UStG, UStDV §§ 33/34/34a, E-RechV): issuer/receiver × B2B/B2G/B2C, transition 2026 → 2027 (€800k) → 2028, exemptions, formats, Leitweg-ID — with primary sources, lastVerified and a non-advice disclaimer | | list_capabilities | Introspection: formats/profiles, bundled standard versions, KB stats, code lists, legal lastVerified, tools/resources/prompts, sovereignty statement | | explain_rule | Explain a rule id such as BR-DE-15 (official text, explanation, affected BTs, fix hint); unknown ids get suggestions |

Every document tool accepts either file_path (absolute; .xml/.pdf; ≤ 20 MB, KONTOR_MAX_FILE_MB) or content_base64 (+ optional content_type), and lang: "de" | "en" (default de).

Resources: kontor://samples/{name} — bundled sample invoices (valid-xrechnung-ubl.xml, valid-xrechnung-cii.xml, broken-missing-buyer-reference.xml, valid-zugferd-en16931.pdf, generated-zugferd-en16931.pdf).

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "kontor": {
      "command": "npx",
      "args": ["-y", "@kontor-mcp/server"]
    }
  }
}

From a local checkout (before the npm publish):

{
  "mcpServers": {
    "kontor": {
      "command": "node",
      "args": ["/absolute/path/to/kontor-mcp/packages/server/dist/bin.js"]
    }
  }
}

Use an absolute path to node (which node) if Desktop cannot find it — it launches servers with a minimal PATH. Quit Desktop fully (⌘Q) and reopen; the config is read at launch. Logs: ~/Library/Logs/Claude/mcp-server-kontor.log.

Restart Claude Desktop, attach an invoice (or + → Add from kontor → broken-missing-buyer-reference.xml) and ask "Ist diese Rechnung gültig?".

All tools are offline and stateless; all except generate_invoice / convert_invoice (which may write a file when output_path is given) are read-only (readOnlyHint), so it is safe to set them to Always allow under Settings → Connectors → kontor; on first use Desktop shows a "Needs approval" prompt otherwise.

PDFs: Desktop does not hand attached PDF bytes to the server, so reference ZUGFeRD/Factur-X PDFs by local path instead: "Was steht in dieser Rechnung? /path/to/invoice.pdf". XML attachments work either way (the model re-sends them as content_base64).

Claude Code

claude mcp add kontor -- node /absolute/path/to/kontor-mcp/packages/server/dist/bin.js

MCP Inspector

npx @modelcontextprotocol/inspector@latest node packages/server/dist/bin.js
# or headless:
npx @modelcontextprotocol/inspector@latest --cli node packages/server/dist/bin.js --method tools/list

Streamable HTTP

The same server over HTTP (MCP Streamable HTTP, endpoint /mcp) for remote agents, Docker and clients that cannot hand attachment bytes to a stdio server:

KONTOR_TRANSPORT=http KONTOR_AUTH_TOKEN="$(openssl rand -hex 24)" node packages/server/dist/bin.js
# → [kontor-mcp] kontor-mcp 0.9.0 listening on http://127.0.0.1:3333/mcp (auth: bearer, origins: localhost)
npx @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:3333/mcp --transport http \
  --header "Authorization: Bearer $KONTOR_AUTH_TOKEN" --method tools/list

| Variable | Default | Meaning | |---|---|---| | KONTOR_TRANSPORT | stdio | stdio or http | | KONTOR_PORT | 3333 | TCP port (0 = ephemeral) | | KONTOR_BIND | 127.0.0.1 | Bind address. Loopback (127.0.0.1, localhost, ::1) enables Host-header / DNS-rebinding protection | | KONTOR_AUTH_TOKEN | — | Bearer token (≥ 16 chars), compared in constant time. Required in HTTP mode | | KONTOR_ALLOW_NO_AUTH | — | 1 runs without a token — only honoured on a loopback bind (local experiments) | | KONTOR_ALLOWED_ORIGINS | — | Comma-separated browser origins allowed in addition to http(s)://localhost|127.0.0.1|[::1]. Requests without an Origin header (non-browser clients) always pass; any other origin → 403 | | KONTOR_ALLOWED_HOSTS | — | Comma-separated hostnames accepted in the Host header besides loopback (behind a reverse proxy / in a container). On a loopback bind only loopback hosts pass; on 0.0.0.0 without this list the Host header is not checked and the token is the guard | | KONTOR_MAX_SESSIONS | 100 | Concurrent MCP sessions; beyond it new initialize requests get 503 + Retry-After | | KONTOR_SESSION_IDLE_MINUTES | 30 | Sessions without a request for this long are closed (clients that never DELETE) | | KONTOR_MAX_FILE_MB | 20 | Also sizes the JSON body cap (content_base64 inflates by 4/3) |

Behaviour: one MCP session per client (Mcp-Session-Id, UUID), DELETE /mcp ends it, unknown ids → 404; GET /healthz (unauthenticated) returns { ok, name, version, sessions } for container health checks; SIGINT/SIGTERM close all sessions, then the listener. Wrong or missing token → 401 with WWW-Authenticate: Bearer. There is no TLS in the server — terminate it in your reverse proxy (Caddy, nginx, Traefik) and forward to the loopback port; see SECURITY.md.

Docker

The image (Dockerfile at the repo root; multi-stage, node:22-alpine, runs as node, ~70 MB, linux/amd64 + linux/arm64) defaults to KONTOR_TRANSPORT=http, KONTOR_BIND=0.0.0.0, port 3333 and refuses to start without KONTOR_AUTH_TOKEN. A HEALTHCHECK polls /healthz. The samples ship at /app/samples/; mount your own invoices read-only (-v ./invoices:/data:ro) and reference them as /data/<file>.

docker build -t kontor-mcp .
docker run -d --name kontor -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN="$(openssl rand -hex 24)" -v "$PWD/invoices:/data:ro" kontor-mcp
docker run -i --rm -e KONTOR_TRANSPORT=stdio kontor-mcp        # stdio inside a container also works

docker-compose.yml is a hardened example (loopback-published port, read_only, cap_drop: ALL, no-new-privileges, token from .env). CI builds both platforms and runs an Inspector-over-HTTP smoke test against the image on every push.

Privacy / sovereignty

Stateless; nothing is stored or transmitted; invoice contents are never logged (see PRD NFR-2/NFR-5/NFR-6). Findings are formal/technical checks, not tax or legal advice.

Resources and prompts

| URI / name | What | |---|---| | kontor://samples/{name} | Sample invoices (UBL, CII, ZUGFeRD PDF, one broken) | | kontor://reference/rules | Rule knowledge-base index (all EN 16931 / XRechnung rule ids, severity, curated flag) | | kontor://reference/codelists/{list} | units, vat-categories, payment-means, eas, vatex, invoice-types, currencies, countries, allowance-reasons, charge-reasons, identifier-schemes, mime-types, vat-point-date-codes — official code values with DE/EN names for the common ones | | kontor://reference/cheatsheet | One-page EN 16931 / XRechnung / ZUGFeRD orientation incl. the German mandate timeline (Markdown) | | prompt audit-incoming-invoice | Run audit_invoice and present a decision-ready AP summary | | prompt draft-supplier-rejection | Draft (never send) a German rejection e-mail citing the concrete rule violations | | prompt create-invoice-interview | Interview for the minimal XRechnung field set, then generate_invoice |