Skip to main content
Glama

Kontor MCP

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

CI Conformance PDF/A-3 License npm MCP Registry Website

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.

Kontor MCP in Claude Desktop: validate a broken XRechnung, parse a ZUGFeRD PDF, explain BR-DE-18

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.

Related MCP server: eleata e-invoice MCP server

Five-minute quickstart

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

Install path

Command

npx (zero-config stdio)

npx -y @kontor-mcp/server

Docker (Streamable HTTP, token required)

docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN=… ghcr.io/dashankanadeeshandesilva/kontor-mcp

Reference client

npx -y -p @kontor-mcp/client kontor-agent audit invoice.xml

From source

git clone … && pnpm install && pnpm build → node packages/server/dist/bin.js

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:**

```sh
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

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

Every rule set, schema, code list and legal fact is bundled in @kontor-mcp/rules with provenance and checksums. Proven by sovereignty.test.ts: all outbound paths (sockets, DNS, TLS, http/https, fetch) are blocked and recorded while every tool, resource and prompt runs — zero attempts; a static scan allows a network import only in the inbound HTTP host; CI also runs a full audit in a --network none container. See SECURITY.md.

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

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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      InvoiceXML brings e-invoice compliance to your AI agent. Create, validate, convert, render, and extract structured invoices across UBL (Peppol BIS Billing 3.0, used worldwide), CII, Factur-X, ZUGFeRD, and XRechnung, all checked against the EN 16931 standard and official Schematron rules. Ask your assistant to generate a compliant invoice, validate one for errors, or convert between formats, with n
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Validates EU electronic invoices (Peppol, XRechnung, FatturaPA, etc.) and explains validation error codes, enabling AI coding agents to check invoice validity and get fixes before rejection.
      3
      46 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants and agents to create, validate, read and convert German and EU e-invoices in ZUGFeRD, XRechnung and Factur-X formats, including extracting structured data from scanned or PDF invoices and embedding XML into PDF/A-3 files. It can run as a hosted remote server or locally, with each request authenticated by the caller's own API token.
      10
      24 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to locate invoice files, extract embedded ZUGFeRD/Factur-X XML from PDF/A-3 documents, and validate compliance with § 14 UStG and EN 16931, including direct PDF invoice checks.
      3
      1
      MIT