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 an open-source Model Context Protocol server that gives AI assistants (Claude Desktop, Claude Code, any MCP client) fully local capabilities for German/EU electronic invoicing: parse, validate, audit, explain, generate and convert XRechnung and ZUGFeRD/Factur-X invoices with the official KoSIT / EN 16931 rule sets — and no invoice data ever leaving your machine.

Status: v0.9 — full tool surface (8 tools, 4 resource families, 3 prompts), KoSIT conformance 89/89, ZUGFeRD PDF/A-3 generation verified by veraPDF and Mustang. Phase 3 (Streamable HTTP + auth, Docker, kontor-agent CLI, security pass, npm publish → v1.0) is in progress; until the npm publish, install from source as shown below.

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

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 and pnpm 10 (corepack enable picks the pinned version).

git clone https://github.com/DashankaNadeeshanDeSilva/kontor-mcp.git
cd kontor-mcp
pnpm install && pnpm build          # ~1 min; all standards artefacts are bundled — no extra downloads, no Java

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

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

Claude Code:

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

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

Tool	What it does
parse_invoice	Detect the 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 (KoSIT scenarios) + Kontor plausibility → valid / valid_with_warnings / invalid with explained findings
audit_invoice	One call for accounts payable: header facts, VAT breakdown, verdict, grouped findings, accept / review / reject with rationale; stateless duplicate detection via known_invoice_numbers
generate_invoice	Structured data → XRechnung 3.0 (UBL) or ZUGFeRD 2.3 / Factur-X PDF/A-3 (target: zugferd-pdf, profiles EN16931 / BASIC / EXTENDED); decimal-safe amounts, internal validation, deterministic auto-fixes reported
convert_invoice	ZUGFeRD PDF → XML, UBL ↔ CII via the semantic model (post-validated, honest loss report), self-contained HTML preview
check_obligations	German e-invoicing mandate decision tree (B2B/B2G/B2C, 2025 → 2028 transition, exemptions) with primary legal sources
explain_rule	Official text, explanation, affected business terms and fix hint for any BR-* / BR-DE-* / KONTOR-* rule id
list_capabilities	Formats, bundled standard versions, KB stats, legal lastVerified, inventory, sovereignty statement

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

Claim	Proof
No network at runtime	No HTTP client in the dependency tree; every rule set, schema, code list and legal fact is bundled in @kontor-mcp/rules with provenance and checksums. A network-guard test is part of the Phase 3 security pass.
No Java, no native code	Schematron is compiled at build time and executed with Saxon-JS; XSD via xmllint-wasm; PDF via pdf-lib. Java is used only by the development-time oracles (KoSIT validator, veraPDF, Mustang) in CI.
Nothing stored, nothing logged	The server is stateless; invoice contents never reach a log (KONTOR_LOG_PAYLOADS defaults to off).
The verdicts are the official ones	docs/CONFORMANCE.md: 89/89 files of the official XRechnung test suite with identical verdicts and identical findings vs the KoSIT validator, replayed on every CI run.
The PDFs are real PDF/A-3	Every generated sample is regenerated in CI and checked by veraPDF (PDF/A-3b, zero violations) and Mustang CLI (PDF/A + XMP + profile XSD + EN 16931 rules).

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<br/>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

What	Reference	Result (2026-08-25)
Validation verdicts and findings	KoSIT validator 1.6.3, XRechnung 3.0.2 test suite (86 files) + Kontor fixtures (3)	89/89 verdict and finding parity
Generated ZUGFeRD PDFs	veraPDF 1.30.2 (PDF/A-3b)	6/6 PASS, zero violations
Generated ZUGFeRD PDFs	Mustang CLI 2.26.0 (PDF/A + XMP + Factur-X profile XSD + EN 16931)	6/6 valid (EN 16931, BASIC, EXTENDED × DE/EN)
Generated XRechnung	own pipeline (identical to the oracle above), 50 random inputs	50/50 valid and plausible

Details, commands and recorded reports: docs/CONFORMANCE.md.

Packages

Package	Purpose
@kontor-mcp/core	MCP-free library: detect, parse, validate, audit, generate, convert, ZUGFeRD PDF
@kontor-mcp/rules	Bundled standards artefacts (XSDs, compiled Schematron, code lists, legal timeline, PDF assets) + rule knowledge base
@kontor-mcp/server	MCP server (stdio and Streamable HTTP with bearer auth; Docker image) exposing tools, resources, prompts
@kontor-mcp/client	kontor-agent — reference MCP client CLI: tools introspection, scriptable audit <file> (no LLM, exit codes), chat Anthropic agent loop with tool-call trace; stdio or HTTP

FAQ

Is this legal or tax advice? No. Kontor reports formal and technical checks against the published standards and the legal timeline with its sources; decisions remain yours. Every answer carries that disclaimer.

Does it support XRechnung 3.0.2 / the 2025 rules? Yes: XRechnung 3.0.2, Schematron 2.5.0, validator configuration 2026-01-31, EN 16931 1.3.16. Versions are pinned and listed by list_capabilities.

Which ZUGFeRD profiles can it read and write? Read: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG (profile from the XMP). Write: EN 16931 (default), BASIC, EXTENDED — see D-042 for what BASIC drops.

Can I send it a PDF from Claude Desktop? Reference it by local path. Desktop does not pass attached PDF bytes to MCP servers; XML attachments work either way.

Why no Java when KoSIT's validator is Java? Sovereignty and installability: Schematron is compiled once at build time and executed in TypeScript (Saxon-JS). The Java tools are used only as oracles in CI to prove parity.

Windows? Yes — CI runs the full test suite on Ubuntu, macOS and Windows with Node 20 and 22.

Development

pnpm install
pnpm build
pnpm -r test
pnpm lint
pnpm artifacts        # fetch pinned third-party artefacts for the oracles (dev only)
pnpm oracle --diff …  # KoSIT parity (Java 17+)
pnpm check:zugferd    # regenerate samples, veraPDF + Mustang (Java + veraPDF)

Read CONTRIBUTING.md before opening a PR; security issues go through SECURITY.md.

Docs

• Product Requirements · Implementation Plan · Decision log
• Conformance · Business-term coverage · Artefact provenance
• v0.1 Claude Desktop verification

License

Apache-2.0 — see LICENSE and NOTICE for bundled third-party components (KoSIT artefacts Apache-2.0, EN 16931 artefacts EUPL-1.2, Liberation Fonts OFL 1.1, ICC sRGB profile).