Poland Invoice MCP 🇵🇱 — How can my AI agent issue a KSeF structured e-invoice (faktura ustrukturyzowana) in Poland?

<!-- install-cta -->

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.

Tools

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).

Why there is no cancel tool

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)

1. 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).
2. Encrypted session: generate an AES-256 key + IV, encrypt the key with the MoF SymmetricKeyEncryption certificate (RSA-OAEP), POST /sessions/online.
3. 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   # local server on :3231
node test/e2e.js     # protocol + validation + VAT-math asserts + LIVE probes against api-test.ksef.mf.gov.pl

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.