mcp-ksef-pl
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| KSEF_NIP | No | NIP podmiotu wysyłającego faktury | |
| KSEF_TIMEOUT | No | Limit czasu żądań HTTP w sekundach | 30 |
| KSEF_ENVIRONMENT | No | Środowisko KSeF: production, test lub demo | test |
| KSEF_SESSION_TOKEN | No | Token sesji KSeF (uzyskiwany przez przepływ challenge-response z MF) |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
MCP server for Polish electronic invoicing. Supports KSeF FA(2) (national format) and Peppol BIS 3.0 / EN 16931 UBL. Use generate_fa2_invoice → validate_fa2_invoice → submit_invoice_to_ksef for the standard KSeF workflow. Use generate_peppol_invoice for cross-border Peppol invoicing.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| generate_fa2_invoiceA | Generate a KSeF-compliant FA(2) XML invoice from structured invoice data. Returns the FA(2) XML string ready for submission to KSeF. The seller's tax_id must be a Polish NIP (10 digits). |
| generate_fa3_invoiceA | Generate a KSeF-compliant FA(3) XML invoice from structured invoice data. FA(3) is required for all new invoice submissions via KSeF API v2. Use this tool — not generate_fa2_invoice — before calling submit_invoice_to_ksef. The seller's tax_id must be a Polish NIP (10 digits). The buyer's tax_id may be a Polish NIP, a EU VAT number (set alt_tax_id), or absent (leave tax_id.identifier empty to emit ). Returns the FA(3) XML string ready for submit_invoice_to_ksef. |
| validate_fa2_invoiceA | Validate a KSeF FA(2) XML invoice. Runs XSD validation (when the official schema is present) and Polish business-rule checks. Returns a DocumentValidationResult with errors and warnings. |
| parse_fa2_invoiceA | Parse a KSeF FA(2) XML invoice into a structured dictionary. Returns a nested dict with 'header', 'seller', 'buyer', 'invoice', and 'lines' keys. |
| submit_invoice_to_ksefA | Submit a FA(3) XML invoice to the KSeF platform (API v2). KSeF API v2 requires FA(3) format for submission. Use generate_fa2_invoice only for validation or parsing; it produces FA(2) XML which KSeF v2 does not accept. FA(3) generation is tracked in roadmap-2026.md. |
| get_ksef_invoice_statusA | Retrieve the processing status of a submitted KSeF invoice (API v2). |
| search_ksef_invoicesC | Query invoices stored in KSeF for a date range. |
| validate_polish_nipA | Validate a Polish NIP (tax identification number). Applies the official 10-digit checksum algorithm. Accepts NIP with or without dashes/spaces. Returns {'valid': bool, 'nip': str, 'normalized': str}. |
| validate_polish_regonA | Validate a Polish REGON (business registry number — 9 or 14 digits). Returns {'valid': bool, 'regon': str, 'length': int}. |
| generate_peppol_invoiceA | Generate a Peppol BIS Billing 3.0 / EN 16931 UBL 2.1 XML invoice. Use this for cross-border B2B invoicing via the Peppol network. For domestic Polish invoicing, use generate_fa2_invoice instead. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools target clearly distinct resources and actions, and descriptions explicitly disambiguate the risky pairs (generate_fa2_invoice vs generate_fa3_invoice vs generate_peppol_invoice; submit vs status vs search). However, the presence of both FA(2) and FA(3) generators plus a FA(2)-only validator/parser creates a residual confusion risk for an agent that must remember FA(3) is the submission format.
All names follow a strict snake_case verb_noun pattern (generate_*, validate_*, parse_*, search_*, submit_*, get_*). Verb choice is predictable and resource suffixes are consistent across the FA2/FA3/Peppol variants.
Ten tools is well within the appropriate range and each earns its place: three generation formats, submission, status, search, parsing, validation, and two identifier validators. No obviously redundant or filler tools.
The core lifecycle (generate, validate, submit, status, search, parse) is covered, but coverage is asymmetric: parsing and validation exist only for FA(2) while FA(3) is the only format KSeF v2 accepts, so agents can submit but cannot inspect or validate what they submitted. There is also no fetch-by-KSeF-number/download tool and no UPO/confirmation retrieval, leaving dead ends after submission.