einvoice-mcp

Python 3.11+ License: MIT Tests Coverage

MCP-Server for German e-invoice compliance — XRechnung 3.0 & ZUGFeRD 2.x

An MCP server that enables AI agents (Claude, Cursor, Copilot) to validate, generate, parse, and check compliance of electronic invoices per EN 16931 — without a single line of integration code.

Why This Exists

Germany mandated e-invoice reception for B2B as of January 2025 (BMF 2024-11-15). Issuance mandates follow in 2027 (Vorjahresumsatz > 800K) and 2028 (all businesses). Every German company needs tooling — this MCP server gives AI agents that capability.

Compliance Proof

675 tests | 100% coverage (2106 stmts) | 0 failures | lint clean (ruff + mypy strict)

Run make test to verify.

EN 16931 / XRechnung 3.0 Field Coverage

Every mandatory Business Term is tested in generated XML output:

BT	Field	Test	Result
BT-1	Invoice number	`test_contains_invoice_id`	PASS
BT-2	Issue date	`test_produces_valid_xml`	PASS
BT-3	Invoice type code (380/381/384)	`test_type_code_380_rechnung`, `test_type_code_381_gutschrift`	PASS
BT-5	Currency code (EUR)	`test_currency_eur`	PASS
BT-10	Buyer reference / Leitweg-ID	`test_buyer_reference_set`	PASS
BT-27	Seller name	`test_contains_seller`	PASS
BT-31	Seller VAT ID (schemeID=VA)	`test_tax_registration_scheme_id_correct`	PASS
BT-32	Seller tax number (schemeID=FC)	`test_steuernummer_bt32_scheme_fc`	PASS
BT-34	Seller electronic address (schemeID=EM)	`test_seller_electronic_address_bt34`	PASS
BT-35..38	Seller address	`test_contains_seller`	PASS
BT-39	Seller country subdivision	`test_country_subdivision_seller_buyer`	PASS
BT-40	Seller country code	`test_contains_seller`	PASS
BT-41	Seller contact name (BR-DE-5)	`test_seller_contact_br_de_5`	PASS
BT-42	Seller contact phone	`test_seller_contact_phone`	PASS
BT-43	Seller contact email (BR-DE-7)	`test_seller_contact_email_br_de_7`	PASS
BT-44	Buyer name	`test_contains_buyer`	PASS
BT-49	Buyer electronic address (schemeID=EM)	`test_buyer_electronic_address_bt49`	PASS
BT-50..53	Buyer address	`test_contains_buyer`	PASS
BT-54	Buyer country subdivision	`test_country_subdivision_seller_buyer`	PASS
BT-55	Buyer country code	`test_contains_buyer`	PASS
BT-71	Delivery date (§14 Abs. 4 Nr. 6 UStG)	`test_delivery_date_bt71`	PASS
BT-20	Payment terms text	`test_payment_terms_text_roundtrip`	PASS
BT-22	Invoice note	`test_invoice_note_roundtrip`	PASS
BT-73/74	Service period start/end	`test_service_period_bt73_bt74`	PASS
BT-11	Project reference	`test_project_reference_bt11`	PASS
BT-12	Contract reference	`test_contract_reference_bt12`	PASS
BT-13	Purchase order reference	`test_purchase_order_reference_bt13`	PASS
BT-25	Preceding invoice number	`test_preceding_invoice_bt25`	PASS
BT-81	Payment means type code	`test_payment_means_type_code_custom`	PASS
BT-83	Remittance information	`test_remittance_information_roundtrip`	PASS
BT-84	IBAN (SEPA credit transfer)	`test_iban_in_xml`	PASS
BT-9	Due date	`test_due_date_roundtrip`	PASS
BT-14	Sales order reference	`test_sales_order_roundtrip`	PASS
BT-29	Seller registration ID (GLN)	`test_seller_registration_id_roundtrip`	PASS
BT-36/37	Seller address lines 2/3	`test_address_lines_full_roundtrip`	PASS
BT-44	Buyer contact name	`test_buyer_contact_roundtrip`	PASS
BT-46	Buyer contact phone	`test_buyer_contact_roundtrip`	PASS
BT-47	Buyer contact email	`test_buyer_contact_roundtrip`	PASS
BT-51/52	Buyer address lines 2/3	`test_address_lines_full_roundtrip`	PASS
BT-70..80	Delivery location	`test_delivery_location_roundtrip`	PASS
BT-127	Line item note	`test_item_note_roundtrip`	PASS
BT-155	Seller item identifier	`test_seller_item_id_roundtrip`	PASS
BT-156	Buyer item identifier	`test_buyer_item_id_roundtrip`	PASS
BT-157	Standard item ID (GTIN)	`test_standard_item_id_roundtrip`	PASS
BG-20/21	Document-level allowances/charges	`test_allowance_roundtrip`	PASS
BG-27/28	Line-level allowances/charges	`test_line_allowance_roundtrip`	PASS
BT-16	Despatch advice reference	`test_despatch_advice_roundtrip`	PASS
BT-18	Invoiced object identifier	`test_invoiced_object_identifier_roundtrip`	PASS
BT-23	Business process type	`test_business_process_type_roundtrip`	PASS
BT-89	SEPA mandate reference (BG-19)	`test_sepa_direct_debit_roundtrip`	PASS
BT-91	Buyer IBAN (BG-19)	`test_sepa_direct_debit_roundtrip`	PASS
BT-120	VAT exemption reason text (BR-E-10)	`test_exemption_reason_roundtrip`	PASS
BT-121	VAT exemption reason code	`test_exemption_reason_roundtrip`	PASS
BT-28	Seller trading name	`test_trading_names_roundtrip`	PASS
BT-45	Buyer trading name	`test_trading_names_roundtrip`	PASS
BT-17	Tender or lot reference	`test_tender_reference_roundtrip`	PASS
BT-133	Buyer accounting reference	`test_bt133_roundtrip`	PASS
BT-134/135	Line-level billing period	`test_line_period_roundtrip`	PASS
BT-147/148	Gross price / price discount	`test_gross_price_and_discount_roundtrip`	PASS
BT-158	Item classification (CPV, etc.)	`test_item_classification_roundtrip`	PASS
BG-11	Seller tax representative (BT-62..65)	`test_seller_tax_rep_roundtrip`	PASS
BG-10	Payee party (BT-59..61)	`test_payee_party_roundtrip`	PASS
BG-18	Payment card (BT-87/88)	`test_payment_card_roundtrip`	PASS
BT-159	Item country of origin	`test_country_of_origin_roundtrip`	PASS
BG-30	Item attributes (BT-160/161)	`test_single_attribute_roundtrip`	PASS
BT-15	Receiving advice reference	`test_receiving_advice_roundtrip`	PASS
BT-71	Delivery location identifier	`test_delivery_location_id_roundtrip`	PASS
BT-82	Payment means text	`test_payment_means_text_roundtrip`	PASS
BG-24	Supporting documents (BT-122..125)	`test_supporting_doc_with_uri`	PASS
Skonto	Payment discount terms	`test_skonto_roundtrip`	PASS

Calculation Rules

Rule	Description	Test	Result
BR-CO-14	TaxTotalAmount = sum of per-group CalculatedAmount	`test_br_co_14_tax_total_equals_sum_of_trade_tax`	PASS
BR-CO-14	PDF/XML/API totals use identical per-group rounding	`test_total_tax_uses_per_group_rounding`	PASS
BR-CO-10	Line item LineTotalAmount quantized to 0.01	`test_line_item_net_amount_quantized`	PASS
BR-DE-23	IBAN mandatory when PaymentMeansCode=58	`test_iban_missing_flags_bt84`	PASS
§14/4/2	BT-31 or BT-32 must be present	`test_neither_bt31_nor_bt32_flags_missing`	PASS
§14/4/6	BT-71 or BT-73/74 must be present	`test_no_delivery_date_or_period_flags_missing`	PASS
BT-3	TypeCode validated against EN 16931 codes	`test_invalid_type_code_rejected`	PASS
BT-25	Credit note (381) must reference preceding invoice	`test_credit_note_without_bt25_flags_missing`	PASS
384-BT-25	Corrective invoice (384) must reference preceding invoice	`test_384_with_preceding_ref`	PASS
RC-COUNTRY	Reverse charge: seller ≠ buyer country advisory	`test_ae_same_country_advisory`	PASS
IC-COUNTRY	Intra-community: seller ≠ buyer country required	`test_k_same_country_error`	PASS
§13b UStG	Reverse charge: seller+buyer VAT IDs, 0% rate	`test_reverse_charge_*`	PASS
§4/1b UStG	Intra-community (K): buyer VAT ID, 0% rate	`test_k_*`	PASS
§19 UStG	Kleinunternehmer: exemption note advisory	`test_exempt_without_note_suggests_ku`	PASS
LW-FMT	Leitweg-ID format advisory	`test_invalid_leitweg_format`	PASS
VAT-FMT	German USt-IdNr. format advisory (DE + 9 digits)	`test_invalid_german_vat_format`	PASS
§4/1a UStG	Export (G): 0% tax rate	`test_export_g_*`	PASS
§33 UStDV	Kleinbetragsrechnung advisory (≤250€)	`test_small_invoice_gets_kb_hint`	PASS
BR-E-10	Exemption reason required for TaxCategory E	`test_compliance_missing_exemption_reason`	PASS
BR-DE-24	SEPA DD: mandate (BT-89) + buyer IBAN (BT-91)	`test_dd_missing_mandate_and_iban`	PASS
BR-DE-15	Payment terms (BT-20) required for XRechnung	`test_payment_terms_missing`	PASS
BR-DE-20	Max one payment instruction type (no mix CT+DD)	`test_mixed_ct_and_dd_flagged`	PASS
CC-BT-87	Credit card PAN required when code=48	`test_credit_card_missing_pan`	PASS
REP-BT-63	Tax rep VAT ID required when BG-11 present	`test_tax_rep_without_tax_id`	PASS
IBAN	IBAN format validation (ISO 13616)	`test_invalid_iban_*`	PASS
BIC	BIC format validation (ISO 9362)	`test_invalid_bic_*`	PASS

Parsing Fidelity

Scenario	Description	Test	Result
SchemeID stripping	`DE123456789 (VA)` → `DE123456789`	`test_str_element_strips_scheme_id`	PASS
Numeric schemeID	`4000000000098 (9930)` → `4000000000098`	`test_strips_numeric_scheme`	PASS
Description text	`Reisekosten (pauschal)` preserved	`test_preserves_lowercase_parens`	PASS
Unicode safety	`Artikel (3Ü)` preserved (not stripped)	`test_preserves_unicode_parens`	PASS
BT-32 roundtrip	Steuernummer FC generate → parse	`test_steuernummer_roundtrip`	PASS
TypeCode roundtrip	381 Gutschrift generate → parse	`test_type_code_381_roundtrip`	PASS
Delivery date roundtrip	BT-71 generate → parse	`test_delivery_date_roundtrip`	PASS
Service period roundtrip	BT-73/74 generate → parse	`test_service_period_roundtrip`	PASS
Electronic address roundtrip	BT-34 generate → parse	`test_seller_electronic_address_roundtrip`	PASS
Invoice note roundtrip	BT-22 generate → parse	`test_invoice_note_roundtrip`	PASS
Payment terms roundtrip	BT-20 generate → parse	`test_payment_terms_text_roundtrip`	PASS
Payment terms override	BT-20 text overrides days	`test_payment_terms_text_overrides_days`	PASS
Purchase order roundtrip	BT-13 generate → parse	`test_purchase_order_reference_bt13`	PASS
Contract roundtrip	BT-12 generate → parse	`test_contract_reference_bt12`	PASS
Project roundtrip	BT-11 generate → parse	`test_project_reference_bt11`	PASS
Preceding invoice roundtrip	BT-25 generate → parse	`test_preceding_invoice_bt25`	PASS
Remittance roundtrip	BT-83 generate → parse	`test_remittance_information_roundtrip`	PASS
Empty scheme stripping	`"PO-42 ()"` → `"PO-42"`	`test_strips_empty_parens`	PASS
Roundtrip invoice	Generate → Parse → Verify key fields	`test_xrechnung_roundtrip`	PASS
Due date roundtrip	BT-9 generate → parse	`test_due_date_roundtrip`	PASS
Address line 2/3 roundtrip	BT-36/37, BT-51/52 generate → parse	`test_address_lines_full_roundtrip`	PASS
Buyer contact roundtrip	BT-44/46/47 generate → parse	`test_buyer_contact_roundtrip`	PASS
Registration ID roundtrip	BT-29 generate → parse	`test_seller_registration_id_roundtrip`	PASS
Sales order roundtrip	BT-14 generate → parse	`test_sales_order_roundtrip`	PASS
Item identifiers roundtrip	BT-155/156/157 generate → parse	`test_all_item_ids_together`	PASS
Line item note roundtrip	BT-127 generate → parse	`test_item_note_roundtrip`	PASS
Delivery location roundtrip	BT-70..80 generate → parse	`test_delivery_location_roundtrip`	PASS
Allowance roundtrip	BG-20 generate → parse	`test_allowance_roundtrip`	PASS
Charge roundtrip	BG-21 generate → parse	`test_charge_roundtrip`	PASS
Line allowance roundtrip	BG-27 generate → parse	`test_line_allowance_roundtrip`	PASS
Despatch advice roundtrip	BT-16 generate → parse	`test_despatch_advice_roundtrip`	PASS
Invoiced object roundtrip	BT-18 generate → parse	`test_invoiced_object_identifier_roundtrip`	PASS
Business process roundtrip	BT-23 generate → parse	`test_business_process_type_roundtrip`	PASS
SEPA direct debit roundtrip	BG-19 generate → parse	`test_sepa_direct_debit_roundtrip`	PASS
Skonto roundtrip	PaymentDiscountTerms generate → parse	`test_skonto_roundtrip`	PASS
BT-133 roundtrip	Buyer accounting reference generate → parse	`test_bt133_roundtrip`	PASS
Trading names roundtrip	BT-28/BT-45 generate → parse	`test_trading_names_roundtrip`	PASS
Tender reference roundtrip	BT-17 generate → parse	`test_tender_reference_roundtrip`	PASS
Exemption reason roundtrip	BT-120/BT-121 generate → parse	`test_exemption_reason_roundtrip`	PASS
Line period roundtrip	BT-134/BT-135 generate → parse	`test_line_period_roundtrip`	PASS
Seller tax rep roundtrip	BG-11 generate → parse	`test_seller_tax_rep_roundtrip`	PASS
Payee roundtrip	BT-59/60/61 generate → parse	`test_payee_party_roundtrip`	PASS
Payment card roundtrip	BT-87/88 generate → parse	`test_payment_card_roundtrip`	PASS
Gross price roundtrip	BT-147/148 generate → parse	`test_gross_price_and_discount_roundtrip`	PASS
Classification roundtrip	BT-158 generate → parse	`test_item_classification_roundtrip`	PASS
Country of origin roundtrip	BT-159 generate → parse	`test_country_of_origin_roundtrip`	PASS
Item attributes roundtrip	BT-160/161 generate → parse	`test_single_attribute_roundtrip`	PASS
Receiving advice roundtrip	BT-15 generate → parse	`test_receiving_advice_roundtrip`	PASS
Delivery location ID roundtrip	BT-71 generate → parse	`test_delivery_location_id_roundtrip`	PASS
Payment means text roundtrip	BT-82 generate → parse	`test_payment_means_text_roundtrip`	PASS
Supporting docs roundtrip	BG-24 generate → parse	`test_supporting_doc_with_uri`	PASS
Supporting docs + tender ref	BG-24 + BT-17 coexistence	`test_supporting_docs_coexist_with_tender_ref`	PASS
Country subdivision roundtrip	BT-39/BT-54 generate → parse	`test_country_subdivision_seller_buyer`	PASS
Payment means type code roundtrip	BT-81 generate → parse	`test_sepa_type_code_roundtrip`	PASS
Buyer reference roundtrip	BT-10 generate → parse	`test_buyer_reference_roundtrip`	PASS
Tax rep subdivision roundtrip	BG-11 BT-39 generate → parse	`test_tax_rep_subdivision_roundtrip`	PASS
Combined item features	BT-159 + BG-30 + BT-148 together	`test_all_item_features_together`	PASS
Multi-reference coexistence	BT-17 + BT-18 in same invoice	`test_tender_and_invoiced_object_coexist`	PASS
Non-ASCII party names	Cyrillic/Chinese names	`test_non_ascii_party_names`	PASS
All type codes	380, 381, 384, 389, 875, 876, 877	`test_all_type_codes`	PASS
All tax categories	S, Z, E, AE, K, G, O, L, M	`test_all_tax_categories`	PASS
50 line items	Large invoice build + parse	`test_many_line_items`	PASS
Mixed tax categories	S + G items in same invoice	`test_mixed_tax_category_invoice`	PASS
Unicode safety (umlauts)	ÄÖÜäöüß in all text fields	`test_unicode_invoice`	PASS
High-value invoice	50 line items with high amounts	`test_high_value_invoice`	PASS
Mixed tax rates	7% + 19% with exact rounding	`test_reduced_tax_rate`	PASS
Classification version	BT-158-2 version roundtrip	`test_classification_with_version_roundtrip`	PASS
UBL detection	UBL Invoice/CreditNote rejected	`test_ubl_invoice_rejected`	PASS
Defensive handlers	Exception in buyer_reference/tax_rep/payee/exemption	`TestDefensiveExceptionHandlers`	PASS
Pydantic BT mapping	Validation errors show BT numbers	`test_invalid_iban_shows_bt84`	PASS

Tax Category Coverage (All 9 EU VAT Categories)

Category	Code	Description	Result
Standard	S	19% / 7% USt	PASS
Zero	Z	0% rated	PASS
Exempt	E	Exempt	PASS
Reverse charge	AE	Reverse charge (Umkehr der Steuerschuld)	PASS
Intra-community	K	EU supply (innergemeinschaftliche Lieferung)	PASS
Export	G	Outside EU (Drittlandslieferung)	PASS
Not subject	O	No VAT	PASS
Canary Islands	L	IGIC	PASS
Ceuta/Melilla	M	IPSI	PASS

Security Hardening

Attack Vector	Protection	Test	Result
XXE entity expansion	defusedxml pre-screen	`test_parse_xml_blocks_xxe`	PASS
Billion laughs (entity bomb)	defusedxml pre-screen	`test_parse_xml_blocks_billion_laughs`	PASS
External entity injection	defusedxml pre-screen	`test_parse_xml_blocks_external_entity`	PASS
XML bomb (>10 MB)	Size limit	`test_validate_rejects_oversized_xml`	PASS
PDF bomb (>50 MB base64)	Size limit	`test_validate_rejects_oversized_pdf`	PASS
Decoded PDF bomb (>50 MB)	Post-decode guard	`test_validate_rejects_oversized_decoded_pdf`	PASS
KoSIT response bomb	10 MB + 512 KB cap	`test_oversized_content_length_header`	PASS
Input reflection in errors	Sanitized	`test_parse_rejects_unknown_file_type`	PASS
Error detail leakage	Generic messages	`test_connection_error_no_hostname_in_message_de`	PASS
SSRF via redirect	`follow_redirects=False`	Defense-in-depth	HARDENED
Supply chain (Docker)	SHA-256 checksum verification	`Dockerfile.kosit`	HARDENED
Container privilege	Non-root user (both containers)	`Dockerfile`, `Dockerfile.kosit`	HARDENED
Port exposure	KoSIT bound to 127.0.0.1 only	`docker-compose.yml`	HARDENED
Supply chain (Python)	`uv.lock` for reproducible builds	`uv.lock`	HARDENED
IBAN injection	ISO 13616 format validation	`test_invalid_iban_*`	HARDENED
BIC injection	ISO 9362 format validation	`test_invalid_bic_*`	HARDENED

Profile Coverage

Profile	Generate	Parse	Validate	Compliance
XRechnung 3.0	PASS	PASS	PASS	PASS
ZUGFeRD EN16931	PASS	PASS	PASS	PASS
ZUGFeRD Basic	PASS*	-	-	-
ZUGFeRD Extended	PASS*	-	-	-

* Generation produces XML with correct guideline URI; full parse/validate/compliance support planned.

Module Coverage

Module	Lines	Description
`config.py`	16	Pydantic settings
`errors.py`	36	Custom exceptions
`models/`	600+	Pydantic models (invoice, party, line items, results, enums)
`prompts/guides.py`	633	14 German tax scenario prompts
`prompts/guides_advanced.py`	511	8 advanced prompts (EU trade, recurring, Schlussrechnung, Proforma, Drittland, Gutschrift)
`prompts/guides_additional.py`	304	5 additional prompts (Berichtigung, RC+Steuervertreter, Teilrechnung, IG deep, Skonto)
`resources/`	1200+	24 resources (schemas, reference codes, compliance, SEPA, CPV, BT-23, VAT exemptions, UNCL 5189)
`services/invoice_builder.py`	576	CII XML generation via drafthorse
`services/invoice_data_builder.py`	320	Flat parameter builder
`services/cii_extractors.py`	457	Party, item, attribute extraction
`services/kosit.py`	80	KoSIT HTTP client
`services/pdf_generator.py`	182	Visual PDF + factur-x embed
`services/xml_parser.py`	720	CII/ZUGFeRD XML parser
`tools/compliance.py`	217	Compliance orchestration
`tools/compliance_checks.py`	795	BR-DE/BR-CO field checks
`tools/arithmetic_checks.py`	230	BR-CO-10/11/12/13/14/15/16 math checks
`tools/generate.py`	50	Generate tools
`tools/parse.py`	39	Parse tool
`tools/validate.py`	33	Validation tools

server.py excluded — FastMCP Context cannot be unit-tested; helpers tested in test_server_helpers.py.

Tools

Tool	Description
`einvoice_validate_xrechnung`	Validates XRechnung XML against the KoSIT Validator
`einvoice_validate_zugferd`	Validates ZUGFeRD PDF (extracts + validates embedded XML)
`einvoice_generate_xrechnung`	Generates an XRechnung-compliant CII XML invoice
`einvoice_generate_zugferd`	Generates a ZUGFeRD hybrid PDF (visual + machine-readable)
`einvoice_parse`	Parses e-invoices (XML or PDF) into structured data
`einvoice_check_compliance`	Checks mandatory fields + KoSIT validation with German suggestions

MCP Resources

Resource URI	Description
`einvoice://schemas/line-item`	JSON-Schema für Rechnungspositionen (items-Array)
`einvoice://schemas/allowance-charge`	JSON-Schema für Zu-/Abschläge
`einvoice://schemas/item-attribute`	JSON-Schema für Artikelmerkmale (BG-30)
`einvoice://schemas/supporting-document`	JSON-Schema für Belegdokumente (BG-24)
`einvoice://schemas/invoice-data`	Vollständiges JSON-Schema für InvoiceData
`einvoice://reference/type-codes`	Rechnungstyp-Codes (380, 381, 384, 389, 875, 876, 877)
`einvoice://reference/payment-means-codes`	Zahlungsart-Codes (58=SEPA, 59=Lastschrift, 48=Kreditkarte, …)
`einvoice://reference/tax-categories`	EU-USt-Kategorien (S, Z, E, AE, K, G, O, L, M) mit Erklärungen
`einvoice://reference/unit-codes`	Mengeneinheiten-Codes (H87=Stück, HUR=Stunde, KGM=kg, …)
`einvoice://reference/eas-codes`	Elektronische Adress-Schemata (EM=E-Mail, 9930=USt-IdNr., …)
`einvoice://system/kosit-status`	On-demand KoSIT-Validator Statusabfrage
`einvoice://reference/e-rechnung-pflichten`	Zeitplan E-Rechnungspflichten 2020–2028 mit Rechtsgrundlagen
`einvoice://reference/br-de-rules`	Deutsche Geschäftsregeln (BR-DE-1..24) mit Lösungshinweisen
`einvoice://reference/skr04-mapping`	SKR04-Kontenzuordnung für häufige Rechnungsarten (DATEV)
`einvoice://reference/credit-note-reasons`	Gutschrift-Gründe und Korrektur-Codes mit Empfehlungen
`einvoice://reference/leitweg-id-format`	Leitweg-ID Aufbau (Grobadresse-Feinadresse-Prüfziffer), Regex, Beispiele
`einvoice://reference/tax-category-decision-tree`	Steuerkategorie-Entscheidungsbaum (S/Z/E/AE/K/G/O/L/M) mit Szenarien
`einvoice://reference/sepa-mandate-type-codes`	SEPA-Mandatstypen (CORE/B2B), Sequenztypen (FRST/RCUR/OOFF), Gläubiger-ID
`einvoice://reference/cpv-classification-codes`	CPV-Codes für öffentliche Vergabe (BT-158), IT/Bau/Beratung/Gesundheit
`einvoice://reference/business-process-identifiers`	BT-23 Geschäftsprozesstyp-Kennungen (Peppol BIS, XRechnung)
`einvoice://reference/vat-exemption-reason-texts`	USt-Befreiungsgründe (BT-120/BT-121) — §19, §4, §13b UStG mit Texten
`einvoice://reference/uncl-5189-allowance-reason-codes`	UNCL 5189 Zu-/Abschlagsgrund-Codes (Rabatt, Skonto, Zuschläge)

MCP Prompts

Prompt	Description
`gutschrift_erstellen`	Schritt-für-Schritt: Gutschrift (381) erstellen
`reverse_charge_checkliste`	Checkliste: Reverse Charge (§13b UStG, Kategorie AE)
`xrechnung_schnellstart`	Schnellstart: XRechnung für öffentliche Auftraggeber
`korrekturrechnung_erstellen`	Anleitung: Korrekturrechnung (384) erstellen
`abschlagsrechnung_guide`	Abschlagsrechnung / Teilrechnung (TypeCode 875/876/877)
`ratenzahlung_rechnung`	Rechnung mit Ratenzahlung erstellen
`handwerkerrechnung_35a`	Handwerkerrechnung nach §35a EStG
`typecode_entscheidungshilfe`	Entscheidungshilfe: Welcher TypeCode für welchen Anlass?
`b2b_pflicht_2027`	Checkliste: B2B E-Rechnungspflicht ab 2027 vorbereiten
`steuerprüfung_checkliste`	E-Rechnungen für Betriebsprüfung vorbereiten (GoBD, §147 AO)
`kleinunternehmer_guide`	Kleinunternehmer (§19 UStG) — E-Rechnung ohne Umsatzsteuer
`bauleistungen_13b_guide`	Bauleistungen / §13b UStG — Reverse Charge im Baugewerbe
`differenzbesteuerung_25a_guide`	Differenzbesteuerung (§25a UStG) für Gebrauchtwarenhändler
`stornobuchung_workflow`	Stornierung: 381 vs 384 vs neue 380 — Entscheidungsbaum
`reiseleistungen_25_guide`	Reiseleistungen (§25 UStG) — Margenbesteuerung
`innergemeinschaftliche_lieferung_guide`	Innergemeinschaftliche Lieferung (§4 Nr. 1b / §6a UStG)
`dauerrechnung_guide`	Dauerrechnung / Monatsrechnung für wiederkehrende Leistungen
`steuernummer_vs_ustidnr_guide`	Steuernummer vs. USt-IdNr. — Entscheidungshilfe (BR-DE-26)
`schlussrechnung_nach_abschlag`	Schlussrechnung nach Abschlagszahlungen (prepaid_amount, BT-113)
`proforma_rechnung_guide`	Proforma-Rechnung — rechtliche Einordnung, E-Rechnungs-Behandlung
`drittlandlieferung_guide`	Export außerhalb EU (§4 Nr. 1a UStG, Steuerkategorie G, Incoterms)
`gutschriftverfahren_389_guide`	Gutschriftverfahren / Self-Billing (TypeCode 389, §14 Abs. 2)
`rechnungsberichtigung_vs_storno`	381 vs 384: Gutschrift, Korrektur oder Storno? Entscheidungsbaum
`reverse_charge_steuervertreter_combined`	Reverse Charge + Steuervertreter (BG-11): Kombiniertes Szenario
`teilrechnung_workflow`	875 → 877 Lifecycle: Abschlag, Teilrechnung, Schlussrechnung
`innergemeinschaftliche_deep_dive`	IG Lieferung: Gelangensbestätigung, ZM, Nachweispflichten, eVatR
`skonto_berechnung_guide`	Skonto: Berechnung, BT-20 Kodierung, §17 UStG Steuerbehandlung

Quick Start

Prerequisites

Python 3.11+
Docker (for the KoSIT Validator)

Installation

git clone https://github.com/Mavengence/einvoice-mcp.git
cd einvoice-mcp
pip install -e ".[dev]"

Start KoSIT Validator

make docker-up

Starts the KoSIT Validator (v1.6.2, XRechnung scenarios v2026-01-31) on port 8081.

Local Operation (stdio)

make dev

Configuration

Claude Desktop

{
  "mcpServers": {
    "einvoice": {
      "command": "python",
      "args": ["-m", "einvoice_mcp"],
      "env": {
        "KOSIT_URL": "http://localhost:8081"
      }
    }
  }
}

Claude Code

claude mcp add einvoice -- python -m einvoice_mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "einvoice": {
      "command": "python",
      "args": ["-m", "einvoice_mcp"],
      "env": {
        "KOSIT_URL": "http://localhost:8081"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
`KOSIT_URL`	`http://localhost:8081`	KoSIT Validator URL
`LOG_LEVEL`	`INFO`	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Example Prompts

Validiere diese XRechnung: [XML einfügen]

Erstelle eine Rechnung von TechCorp GmbH (DE123456789) an ClientCorp GmbH
für 40 Stunden Software-Beratung à 150€/Stunde mit 19% USt.

Parse diese E-Rechnung und zeig mir die Positionen.

Prüfe ob diese Rechnung XRechnung-konform ist und gib Verbesserungsvorschläge.

Advanced Examples

Erstelle eine Gutschrift (TypeCode 381) für Rechnung RE-2025-099 über
200€ netto mit 19% USt.

Erstelle eine Rechnung mit Reverse Charge (§13b UStG, Kategorie AE):
Verkäufer DE123456789, Käufer ATU12345678, Dienstleistung 5.000€.

Erstelle eine Rechnung mit 2% Skonto bei Zahlung innerhalb von 10 Tagen.

Erstelle eine Rechnung mit SEPA-Lastschrift (PaymentMeansCode 59),
Käufer-IBAN DE89370400440532013000, Mandatsreferenz MREF-2025-001.

Erstelle eine Rechnung mit Lieferort: Lager Hamburg, Hafenstraße 42,
20457 Hamburg.

Erstelle eine innergemeinschaftliche Lieferung (Kategorie K) an
einen französischen Kunden (FR12345678901).

Erstelle eine steuerbefreite Rechnung (§19 UStG, Kleinunternehmer)
mit Befreiungsgrund und Code vatex-eu-132.

Erstelle eine Rechnung für ein Vergabeverfahren mit Losnummer VERGABE-2026-42
und Kontierungsreferenz KST-4711 pro Position.

Erstelle eine Korrekturrechnung (TypeCode 384) für die fehlerhafte Rechnung
RE-2026-001 mit korrigiertem Steuersatz.

Architecture

[AI Client] --> stdio --> [FastMCP Server]
                              |-- drafthorse (CII XML generation/parsing)
                              |-- factur-x (PDF/A-3 embedding/extraction)
                              |-- reportlab (Visual PDF rendering)
                              |-- defusedxml (XXE protection on all parse paths)
                              '-- httpx --> [KoSIT Validator :8081]

KoSIT Validator Stack

Component	Version	Source
KoSIT Validator	v1.6.2 (SHA-256 verified)	itplr-kosit/validator
XRechnung Scenarios	v2026-01-31 (SHA-256 verified)	itplr-kosit/validator-configuration-xrechnung
Java Runtime	Eclipse Temurin 17	OpenJDK

Development

make install    # Install dependencies
make test       # Run tests with coverage
make lint       # Ruff + mypy strict
make fmt        # Format code
make docker-up  # Start Docker stack

Supported Business Terms (EN 16931)

BT/BG	Field	Generate	Parse	Compliance
BT-1	Invoice number	Yes	Yes	Yes
BT-2	Issue date	Yes	Yes	Yes
BT-3	Type code (380/381/384)	Yes	Yes	Yes
BT-5	Currency code	Yes	Yes	Yes
BT-9	Due date	Yes	Yes	—
BT-10	Buyer reference / Leitweg-ID	Yes	Yes	Yes
BT-11	Project reference	Yes	Yes	—
BT-12	Contract reference	Yes	Yes	—
BT-13	Purchase order reference	Yes	Yes	—
BT-14	Sales order reference	Yes	Yes	—
BT-16	Despatch advice reference	Yes	Yes	—
BT-17	Tender or lot reference	Yes	Yes	—
BT-18	Invoiced object identifier	Yes	Yes	—
BT-20	Payment terms text	Yes	Yes	—
BT-22	Invoice note	Yes	Yes	—
BT-23	Business process type	Yes	Yes	—
BT-25	Preceding invoice (credit notes)	Yes	Yes	Yes
BT-27..40	Seller party + address (incl. lines 2/3, subdivision)	Yes	Yes	Yes
BT-28	Seller trading name	Yes	Yes	—
BT-29	Seller registration ID (GLN)	Yes	Yes	—
BT-31	Seller VAT ID (schemeID=VA)	Yes	Yes	Yes
BT-32	Seller tax number (schemeID=FC)	Yes	Yes	Yes
BT-34	Seller electronic address	Yes	Yes	Yes
BT-41	Seller contact name	Yes	Yes	Yes
BT-42	Seller contact phone	Yes	Yes	Yes
BT-43	Seller contact email	Yes	Yes	Yes
BT-44..55	Buyer party + address (incl. lines 2/3, subdivision)	Yes	Yes	Yes
BT-45	Buyer trading name	Yes	Yes	—
BT-46	Buyer registration ID (GLN)	Yes	Yes	—
BT-49	Buyer electronic address	Yes	Yes	Yes
BT-70..80	Delivery location (name + address)	Yes	Yes	—
BT-71	Delivery date	Yes	Yes	Yes
BT-73/74	Service period	Yes	Yes	Yes
BT-81	Payment means type code	Yes	Yes	—
BT-83	Remittance information	Yes	Yes	—
BT-84	Seller IBAN	Yes	Yes	Yes
BT-86	BIC	Yes	Yes	—
BT-89	SEPA mandate reference	Yes	Yes	Yes
BT-91	Buyer IBAN (SEPA direct debit)	Yes	Yes	Yes
BT-120	VAT exemption reason text	Yes	Yes	Yes
BT-121	VAT exemption reason code	Yes	Yes	—
BT-127	Line item note	Yes	Yes	—
BT-155	Seller item identifier	Yes	Yes	—
BT-156	Buyer item identifier	Yes	Yes	—
BT-157	Standard item ID (GTIN/EAN)	Yes	Yes	—
BT-159	Item country of origin	Yes	Yes	—
BT-160/161	Item attributes (BG-30, name/value)	Yes	Yes	—
BG-20/21	Document-level allowances/charges	Yes	Yes	—
BG-27/28	Line-level allowances/charges	Yes	Yes	—
BT-15	Receiving advice reference	Yes	Yes	—
BT-71	Delivery location identifier	Yes	Yes	—
BT-82	Payment means text	Yes	Yes	—
BG-24	Supporting documents (BT-122..125)	Yes	Yes	—
BT-133	Buyer accounting reference	Yes	Yes	—
Skonto	Payment discount terms (percent, days)	Yes	Yes	—

Gutschrift (Credit Note) Support

For credit notes (TypeCode 381), the server:

Sets XML header name to "GUTSCHRIFT" and PDF title accordingly
Requires BT-25 (preceding invoice number) in compliance checks
Shows "Bezug: [Rechnungsnummer]" in the PDF header
Validates against EN 16931 type code whitelist (380, 381, 384, 389, 875, 876, 877)

Example: type_code="381", preceding_invoice_number="RE-2025-099"

Profile Selection Guide

Profile	Use Case	Guideline URI
`XRECHNUNG`	German public sector (B2G), Leitweg-ID required	`urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0`
`ZUGFERD_EN16931`	B2B invoices (default for ZUGFeRD PDF)	`urn:cen.eu:en16931:2017`
`ZUGFERD_BASIC`	Simplified B2B invoices	`urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic`
`ZUGFERD_EXTENDED`	Extended B2B invoices with additional fields	`urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended`

German Compliance Guide

See docs/GERMAN_COMPLIANCE_GUIDE.md for:

TypeCode decision tree (380/381/384/875/876/877)
Tax category decision tree (S/Z/E/AE/K/G/O/L/M)
Leitweg-ID format and sources
Reverse charge vs. intra-community supply
Handwerkerrechnung §35a EStG
Pflichtfelder-Checkliste for XRechnung 3.0

Limitations

ZUGFeRD Basic/Extended: Generation produces XML with correct guideline URIs, but parsing, validation, and compliance checks are tested for XRechnung 3.0 and ZUGFeRD EN16931 only.
Batch processing: Each tool call processes one invoice. For bulk operations, call the tools in sequence.

Troubleshooting

KoSIT Validator nicht erreichbar

Fehler: KoSIT-Validator nicht erreichbar. Bitte prüfen Sie die Verbindung.

Start the Docker containers: make docker-up
Wait for healthy status: docker compose -f docker/docker-compose.yml ps
Verify manually: curl http://localhost:8081/server/health
Check if port 8081 is blocked by firewall or another process

Docker Container startet nicht

# Check logs
docker compose -f docker/docker-compose.yml logs kosit

# Common issue: port already in use
lsof -i :8081

# Restart clean
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d

UBL-Format erkannt

Fehler: UBL-Format erkannt. Dieses Tool unterstützt nur CII.

The parser only supports CII (Cross Industry Invoice) XML, which is the standard for XRechnung and ZUGFeRD. If you have a UBL invoice, convert it to CII first using an external tool.

Pydantic Validation Errors

When generating invoices, field errors now reference BT numbers:

Fehler: Ungültige Rechnungsdaten:
  - BT-84 (IBAN): String should match pattern ...
  - BT-27 (Verkäufername): String should have at least 1 character

Check the German Compliance Guide for field requirements.

Tests laufen nicht

# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests only (no Docker needed)
make test

# Run integration tests (requires Docker)
make docker-up
pytest -m integration

Regulatory References

EN 16931 — European standard for electronic invoicing
XRechnung 3.0 (Szenarien 3.0.2) — German CIUS (Core Invoice Usage Specification)
ZUGFeRD 2.x / Factur-X 1.08 — Hybrid PDF/A-3 invoice format
BMF 2024-11-15 — German Federal Ministry of Finance e-invoice mandate
§14 UStG — German VAT Act invoice requirements
§14 Abs. 4 Nr. 2 UStG — Steuernummer or USt-IdNr. required (BT-31 / BT-32)
§14 Abs. 4 Nr. 6 UStG — Delivery date or service period required (BT-71 / BT-73/74)
BR-CO-14 — Tax total must equal sum of per-group calculated amounts
BR-DE-5 — Seller contact person (mandatory for XRechnung)
BR-DE-7 — Seller contact email (mandatory for XRechnung)
BR-DE-23 — IBAN mandatory when PaymentMeansCode = 58 (SEPA)
§13b UStG — Reverse charge: seller + buyer VAT IDs required, 0% tax rate
§4 Nr. 1b UStG — Intra-community supply: buyer VAT ID required, 0% tax rate
§19 UStG — Kleinunternehmerregelung: exemption note advisory for TaxCategory E
BG-19 — SEPA direct debit (PaymentMeansCode = 59, buyer IBAN, mandate reference)
BR-DE-20 — Max one payment instruction type (no mixing credit transfer + direct debit)
BR-DE-24 — SEPA direct debit: mandate reference + buyer IBAN required
BR-E-10 — VAT exemption reason (BT-120) required for TaxCategory E
§4 Nr. 1a UStG — Export outside EU (TaxCategory G): 0% tax rate required
§33 UStDV — Kleinbetragsrechnung advisory (invoices ≤250€ gross)
Skonto — Early payment discount terms (PaymentDiscountTerms in CII)
384 Korrekturrechnung — Corrective invoice must reference preceding invoice (BT-25)
RC-COUNTRY — Reverse charge: seller/buyer country advisory (§13b allows domestic)
IC-COUNTRY — Intra-community: seller ≠ buyer country required
§632a BGB — Abschlagsrechnung for construction/service contracts
§35a Abs. 3 EStG — Handwerkerleistungen tax deduction (20% of labor, max 1.200€/year)
§271 BGB — Payment due date per agreement (Ratenzahlung)
ISO 13616 — IBAN format validation (seller + buyer)
ISO 9362 — BIC/SWIFT format validation

License

MIT