einvoice-mcp

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

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
.github/workflows		.github/workflows
docker		docker
docs		docs
src/einvoice_mcp		src/einvoice_mcp
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml
render.yaml		render.yaml
smithery.yaml		smithery.yaml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

einvoice-mcp

Why This Exists

Compliance Proof

EN 16931 / XRechnung 3.0 Field Coverage

Calculation Rules

Parsing Fidelity

Tax Category Coverage (All 9 EU VAT Categories)

Security Hardening

Profile Coverage

Module Coverage

Tools

MCP Resources

MCP Prompts

Quick Start

Prerequisites

Installation

Start KoSIT Validator

Local Operation (stdio)

Configuration

Claude Desktop

Claude Code

Cursor

Environment Variables

Example Prompts

Advanced Examples

Architecture

KoSIT Validator Stack

Development

Supported Business Terms (EN 16931)

Gutschrift (Credit Note) Support

Profile Selection Guide

German Compliance Guide

Limitations

Troubleshooting

KoSIT Validator nicht erreichbar

Docker Container startet nicht

UBL-Format erkannt

Pydantic Validation Errors

Tests laufen nicht

Regulatory References

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages