Skip to main content
Glama
mcp-ksef-pl

mcp-ksef-pl

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
KSEF_NIPNoNIP podmiotu wysyłającego faktury
KSEF_TIMEOUTNoLimit czasu żądań HTTP w sekundach30
KSEF_ENVIRONMENTNoŚrodowisko KSeF: production, test lub demotest
KSEF_SESSION_TOKENNoToken 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

CapabilityDetails
tools
{
  "listChanged": true
}
logging
{}
prompts
{
  "listChanged": true
}
resources
{
  "subscribe": false,
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.7/5.0

Scored across 10 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness3/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues