Kontor MCP

Kontor MCP

The sovereign e-invoice toolkit for AI agents. Official XRechnung / EN 16931 validation, ZUGFeRD in *and* out, 100 % offline, zero API keys.

Kontor MCP is a local, offline toolbox that lets AI assistants (Claude Desktop, Claude Code, any MCP client) handle German/EU e-invoices: XRechnung and ZUGFeRD/Factur-X under EN 16931. It can read an invoice (bare XML or XML embedded in a PDF), check it against the official KoSIT / EN 16931 rulebooks, explain cryptic errors in German or English, create valid new invoices (XML or ZUGFeRD PDF/A-3), convert between formats, and tell a business which legal obligations apply. The key promise is sovereignty: no cloud, no API keys, no network calls, no Java at runtime — proven by tests.

Why it matters: since 2025 every German business must be able to *receive* e-invoices, and from 2027/2028 must *issue* them. An e-invoice is validated XML, not a PDF, and a failed rule can cost the input-VAT deduction. Invoices carry personal and bank data, so they should be checked where they live — on your machine — with the same rule sets the public-sector receivers use.

*Claude Desktop with the kontor server: validate → BR-DE-15 (missing Leitweg-ID) with fix hint · parse a ZUGFeRD PDF · explain BR-DE-18. MP4*

v1.0 — 8 tools · 4 resource families · 3 prompts · KoSIT conformance 89/89 enforced as a CI gate · ZUGFeRD PDF/A-3 output verified by veraPDF and Mustang · stdio and Streamable HTTP (bearer auth) · Docker image (amd64/arm64) · kontor-agent reference client · listed in the Official MCP Registry. Install with npx, Docker, or from source.

Why

• Official rules, not approximations. The KoSIT XRechnung Schematron and the CEN EN 16931 rules run unmodified (compiled to XSLT/SEF, executed with Saxon-JS) with the KoSIT scenario model — the same verdicts the public-sector receivers produce, proven file-by-file against the official validator.
• Sovereign by construction. Pure TypeScript/WASM, no Java at runtime, no network calls, nothing stored, nothing logged. Runs where the invoices are.
• Agent-native. Every tool returns structured content *and* a readable summary; findings carry DE/EN explanations, affected business terms and fix hints; generation is fail-honest (valid is the real verdict, never assumed).
• ZUGFeRD both ways. Read the embedded XML out of any ZUGFeRD/Factur-X PDF; write PDF/A-3 invoices with factur-x.xml that pass veraPDF and Mustang.

Five-minute quickstart

Requires Node ≥ 20. Everything — rules, schemas, code lists, fonts — ships inside the npm package; no downloads at runtime, no Java.

Claude Desktop — Settings → Developer → Edit Config, then quit (⌘Q) and reopen:

{

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

(From a source checkout use "command": "node", "args": ["/absolute/path/to/kontor-mcp/packages/server/dist/bin.js"] instead.)

Claude Code:

claude mcp add kontor -- npx -y @kontor-mcp/server

Now audit a sample invoice. Ask Claude:

Audit /absolute/path/to/kontor-mcp/packages/server/samples/broken-missing-buyer-reference.xml — is it valid?

You get a verdict (invalid), the finding BR-DE-15 (missing buyer reference / Leitweg-ID) with an explanation and fix hint, the recomputed totals and VAT breakdown, and a *reject* recommendation with its rationale. Then try a ZUGFeRD PDF:

What is in /absolute/path/to/kontor-mcp/packages/server/samples/generated-zugferd-en16931.pdf?

(Attach XML files directly if you prefer; PDFs must be referenced by local path — Claude Desktop does not hand PDF bytes to MCP servers.)

Without a chat client, the MCP Inspector works headless:

npx @modelcontextprotocol/inspector@latest --cli node packages/server/dist/bin.js \

--method tools/call --tool-name audit_invoice \ --tool-arg file_path=$PWD/packages/server/samples/broken-missing-buyer-reference.xml --tool-arg lang=en

`kontor-agent` CLI — the reference client; audit needs no LLM and returns 0/1/2 for accept/review/reject, chat is an Anthropic agent loop that prints every tool call (needs ANTHROPIC_API_KEY):

node packages/client/dist/bin.js audit packages/server/samples/broken-missing-buyer-reference.xml --lang en

node packages/client/dist/bin.js chat -m "Prüfe $PWD/packages/server/samples/valid-zugferd-en16931.pdf" node packages/client/dist/bin.js --url http://127.0.0.1:3333/mcp --token "$KONTOR_AUTH_TOKEN" tools # against Docker / HTTP

Docker / Streamable HTTP — the same server over HTTP for remote agents and containers (token required, loopback-published port, TLS is your reverse proxy's job):

docker build -t kontor-mcp .              # multi-stage, non-root, ~70 MB, amd64 + arm64

docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN="$(openssl rand -hex 24)" kontor-mcp curl -s http://127.0.0.1:3333/healthz # {"ok":true,"name":"kontor-mcp",...}

Or cp .env.example .env && docker compose up -d (read-only root FS, ./invoices mounted at /data). Config surface and the security posture: packages/server/README.md, SECURITY.md.

Tools

Resources: kontor://samples/{name}, kontor://reference/rules, kontor://reference/codelists/{list}, kontor://reference/cheatsheet. Prompts: audit-incoming-invoice, draft-supplier-rejection, create-invoice-interview. Full reference with inputs and conventions: packages/server/README.md.

Sovereignty — and how we prove it

Architecture

flowchart LR

subgraph client [MCP client] A[Claude Desktop / Claude Code / kontor-agent] end A -- stdio / Streamable HTTP --> S

subgraph server ["@kontor-mcp/server"] S[tools · resources · prompts Zod schemas, structuredContent + text] end

subgraph core ["@kontor-mcp/core (MCP-free library)"] D[detect] --> P[parse → EN 16931 model] P --> V[validate: XSD → Schematron → plausibility] P --> G[generate / convert / preview] G --> Z[ZUGFeRD PDF/A-3 assembly] V --> AU[audit → verdict + recommendation] O[obligations decision tree] end

subgraph rules ["@kontor-mcp/rules (bundled, checksummed)"] R1[XSDs UBL 2.1 / CII D16B] R2[EN 16931 + XRechnung Schematron as SEF] R3[rule knowledge base DE/EN] R4[code lists · legal timeline · fonts + ICC] end

S --> core core --> rules

The validation pipeline: Layer 1 XSD (xmllint-wasm) → Layer 2 official Schematron (Saxon-JS, KoSIT scenario selection and severity overrides) → Layer 3 Kontor plausibility (KONTOR-PLAUS-*: decimal recomputation, VAT rates, IBAN/BIC, Leitweg-ID check digits, dates, duplicates — never changes the official verdict). Money math is decimal.js only; every XML parse has DTD/external entities disabled.

Conformance

| Generated ZUGFeRD PDFs | Mustang CLI 2.26.0 (PDF/A + XMP + Factur-X profile XSD + EN 16931) | 6/6 valid (EN 16931, BASIC, EXTENDE