MCP Ksef Pl

mcp-ksef-pl 🇵🇱

English | Polski

A Python MCP server providing tools for Polish electronic invoicing compliant with KSeF (FA(2)) and Peppol BIS Billing 3.0 / EN 16931. It enables AI agents (Claude, IDEs) to generate, validate, and submit invoices to the Krajowy System e-Faktur (KSeF), as well as validate Polish tax identifiers (NIP and REGON).

Introduction

This package is built on mcp-einvoicing-core, the shared base library for European e-invoicing MCP servers. It provides an OAuth2 HTTP client, token cache, data models, logging utilities, and an exception hierarchy.

mcp-einvoicing-core is installed automatically as a dependency, no additional step is required.

Installation

Via PyPI (recommended)

pip install mcp-ksef-pl

Or without prior installation using uvx:

uvx mcp-ksef-pl

From source

git clone https://github.com/cmendezs/mcp-ksef-pl.git

cd mcp-ksef-pl uv sync --all-extras

Configuration (environment variables)

The EUSR/TSR reporting and MLS tools additionally require the [xslt2] extra (pip install "mcp-ksef-pl[xslt2]") for Schematron validation.

Claude Desktop integration

Add the following configuration to your claude_desktop_config.json file:

{

"mcpServers": { "ksef-pl": { "command": "uvx", "args": ["mcp-ksef-pl"], "env": { "KSEF_ENVIRONMENT": "test", "KSEF_SESSION_TOKEN": " ", "KSEF_NIP": " " } } } }

Cursor integration

Cursor supports MCP servers via stdio. Add the configuration to:

• Globally (all projects): ~/.cursor/mcp.json
• Per project (this repository only): .cursor/mcp.json

{

"mcpServers": { "ksef-pl": { "command": "uvx", "args": ["mcp-ksef-pl"], "env": { "KSEF_ENVIRONMENT": "test", "KSEF_SESSION_TOKEN": " ", "KSEF_NIP": " " } } } }

Reload the Cursor window (Ctrl+Shift+P → *Reload Window*) after saving changes.

Kiro integration

Kiro supports MCP servers through a dedicated configuration file:

• Globally: ~/.kiro/settings/mcp.json
• Workspace: .kiro/settings/mcp.json

{

"mcpServers": { "ksef-pl": { "command": "uvx", "args": ["mcp-ksef-pl"], "env": { "KSEF_ENVIRONMENT": "test", "KSEF_SESSION_TOKEN": " ", "KSEF_NIP": " " }, "disabled": false, "autoApprove": [] } } }

Security tip: instead of entering the token directly, use the syntax

"KSEF_SESSION_TOKEN": "${KSEF_SESSION_TOKEN}", as Kiro resolves shell environment

variables at startup.

Available tools

FA(3) / FA(2) invoice handling

The official FA(2) and FA(3) XSD schemas ship inside the package (src/mcp_ksef_pl/schemas/) and are loaded automatically via importlib.resources — no manual download or configuration is required. validate_fa2_invoice and validate_fa3_invoice run full XSD validation out of the box for every installation.

KSeF lifecycle

Identifier validation

Peppol / EN 16931

Peppol network tools

Peppol participant lookup, service-endpoint lookup, a DNS-only diagnostic, AS4 send, Peppol Directory search, and the OpenPeppol eDEC codelist tools are provided by the shared core Peppol tool plugin (mcp_einvoicing_core.peppol.tools.register_peppol_tools), mounted in server.py with a Poland-specific identifier adapter: a bare NIP (e.g. 1234563218) is normalized to the 9945: Peppol scheme (PL:VAT, per the OpenPeppol eDEC Participant Identifier Schemes code list); an already scheme-qualified identifier (e.g. 9945:1234563218) passes through unchanged. Use these tools to check PEF (Poland's Peppol Access Point for public-procurement B2G invoicing) registration status ahead of generate_peppol_invoice.

peppol_send signs outbound messages with a real wsse:Security signature as of mcp-einvoicing-core v1.20.0 (previously computed and discarded — see CHANGELOG.md v0.8.0).

See the mcp-einvoicing-core README for full parameter documentation on these tools.

Peppol reporting and status tools

Added in v0.8.0 via three opt-in core plugins, mounted unconditionally in server.py. Each raises a clear error at call time (not at registration) if its extra or data directory is missing.

See the mcp-einvoicing-core README for full parameter documentation on these tools.

KSeF authentication

KSeF API v2 uses a multi-step challenge/redeem flow to issue an AccessToken. This MCP server accepts an already-obtained token and cannot automate the signing step (it requires a qualified electronic signature).

Step-by-step flow

1. Account setup. Register at the KSeF portal: https://ksef.mf.gov.pl/. Select the target environment (test or production). The test environment is at https://ksef-test.mf.gov.pl/.

1. Request a challenge. Call the KSeF API to obtain a challenge XML envelope:

   curl -s https://ksef-test.mf.gov.pl/auth/challenge \

-H "Accept: application/json" \ -d '{"contextIdentifier": {"type": "onip", "identifier": "YOUR_NIP"}}' \ -H "Content-Type: application/json"

The response contains a challenge string and a timestamp.

1. Sign the challenge. Build an XML envelope containing the challenge, then sign it with your qualified e-signature. Accepted signing tools:

• Qualified e-signature providers: KIR (Szafir), Certum, Sigillum
• podpis.gov.pl (government signing portal)
• Profil Zaufany (Trusted Profile): https://www.podatki.gov.pl/ksef/

Example using xmlsec1 with a PKCS#12 certificate:

   # Build the challenge XML (template at specs/przyklad-wyzwania.xml)

xmlsec1 --sign --pkcs12 your-cert.p12 --pwd "password" \ --output signed-challenge.xml challenge-template.xml

1. Submit the signed challenge. POST the signed XML to receive an authOperation reference:

   curl -s https://ksef-test.mf.gov.pl/auth/xades-signature \

-H "Content-Type: application/octet-stream" \ --data-binary @signed-challenge.xml

1. Redeem the AccessToken. Exchange the authenticated operation for an AccessToken:

   curl -s https://ksef-test.mf.gov.pl/auth/token/redeem \

-H "Content-Type: application/json" \ -H "Authorization: Bearer "

The response contains accessToken.token and accessToken.context.referenceNumber.

1. Set the token. Export the token for this MCP server:

   export KSEF_SESSION_TOKEN="<the AccessToken from step 5>"

The token is valid for approximately 2 hours from issuance (per MF documentation). After expiry, repeat steps 2-5.

References

• KSeF techni