Poland Invoice MCP 🇵🇱 — How can my AI agent issue a KSeF structured e-invoice (faktura ustrukturyzowana) in Poland?
Use it in 60 seconds
Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):
{
"mcpServers": {
"poland-invoice": {
"type": "http",
"url": "https://inv-pl.wishpool.app/mcp"
}
}
}
Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.
Or run it yourself
Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:
git clone https://github.com/junter1989k-ai/poland-invoice-mcp && cd poland-invoice-mcp && npx vercel --prod
MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.
Remote MCP server that lets any AI agent issue Poland structured e-invoices (faktura ustrukturyzowana, schema FA(3)) through KSeF 2.0 — Krajowy System e-Faktur, the Ministry of Finance national government e-invoice API. It builds the FA(3) XML, runs the encrypted KSeF online-session flow, and returns the assigned KSeF number. Stateless, bring-your-own credentials, never stores anything.
Live endpoint: https://inv-pl.wishpool.app/mcp · Registry: app.wishpool/poland-invoice-mcp
Quick start
{
"mcpServers": {
"poland-invoice": {
"type": "http",
"url": "https://inv-pl.wishpool.app/mcp",
"headers": {
"x-ksef-token": "your-ksef-authorization-token",
"x-ksef-nip": "1234567890",
"x-ksef-mode": "production"
}
}
}
}
Self-mint your x-ksef-token in the Ministry of Finance taxpayer portal (ksef.podatki.gov.pl → Tokeny / Uwierzytelnianie) and pass your 10-digit seller NIP in x-ksef-nip. Omit x-ksef-mode to stay in the MoF TEST environment (no fiscal effect). Your KSeF certificate stays with the Ministry of Finance — this server never sees it.
| Tool | What it does |
|---|
create_invoice | Build an FA(3) structured invoice and submit it to KSeF — seller_name, buyer_nip + buyer_name, invoice_number, items (name, quantity, net_price, vat_rate 23/8/5/0) in, KSeF number out. Seller NIP comes from the header; buyer NIP is validated with the official checksum; per-rate net/VAT and the gross total are computed for you. |
query_invoice | Fetch an invoice by its KSeF number: status ACCEPTED (present in the national KSeF repository under your NIP = fiscal proof). |
Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The cap applies to the invoice gross total (PLN).
KSeF has no cancel/void operation. Once a structured invoice is accepted into the national system it cannot be deleted; a mistake is fixed by issuing a separate correction invoice (faktura korygująca, RodzajFaktury=KOR), which is its own document with its own KSeF number. So this server ships exactly two tools — create_invoice and query_invoice — rather than pretending a cancel exists. (Correction-invoice support can be added later as a distinct create path.)
How it works (KSeF 2.0 flow)
- Auth handshake:
POST /auth/challenge → encrypt token|timestampMs with RSA-OAEP (SHA-256) using the MoF KsefTokenEncryption public certificate → POST /auth/ksef-token → poll GET /auth/{ref} → POST /auth/token/redeem for the access token (JWT).
- Encrypted session: generate an AES-256 key + IV, encrypt the key with the MoF
SymmetricKeyEncryption certificate (RSA-OAEP), POST /sessions/online.
- Submit: AES-256-CBC-encrypt the FA(3) XML,
POST /sessions/online/{ref}/invoices (with plaintext + ciphertext SHA-256 hashes), then POST /sessions/online/{ref}/close and read the KSeF number.
Public encryption certificates are fetched live from GET /security/public-key-certificates (X.509, CN=Ministerstwo Finansów), so key rotation is handled automatically and nothing is embedded.
Develop
node test/serve.js
node test/e2e.js
The e2e suite makes two real calls to the government KSeF test API: the credential-free /auth/challenge round-trip, and a full RSA-OAEP auth handshake with a placeholder token that surfaces KSeF's real structured auth-failure — the deepest verification possible without a portal-minted token.
Safety
Pure stateless translation layer straight to the government KSeF API. The KSeF certification and taxpayer certificate stay with the Ministry of Finance; credentials travel per-request in headers, nothing is stored. Privacy policy.
Sister servers
Invoices: Mexico CFDI 4.0 inv-mx · Chile DTE inv-cl · Brazil NF-e inv-br · Peru CPE inv-pe · India GST inv-in · Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included.
MIT licensed.