Ksefnik — KSeF SDK dla TypeScript / Node.js z MCP serverem dla Claude i Cursor

Otwarte SDK do Krajowego Systemu e-Faktur (KSeF 2.0) — produkcyjny klient HTTP API, silnik reconcyliacji faktur z wyciągami bankowymi (MT940, mBank, ING, PKO BP, Santander) i Model Context Protocol server, który podpina polskie e-faktury bezpośrednio pod Claude Desktop, Cursor i innych agentów AI.

KSeF SDK · KSeF Node.js client · KSeF API · Polish e-Invoice API · National e-Invoice System library · KSeF TypeScript client · KSeF MCP server · e-faktura SDK · KSeF 2.0 client

     

---

O projekcie

Ksefnik to kompletne, otwarte SDK do Krajowego Systemu e-Faktur (KSeF 2.0) — obowiązkowego od 2026-02-01 systemu Ministerstwa Finansów do wystawiania i pobierania faktur elektronicznych w Polsce. Projekt rozwijany przez CodeFormers.it adresuje dwa problemy, które każdy deweloper integrujący się z KSeF musi rozwiązać: produkcyjny klient HTTP do api.ksef.mf.gov.pl (auth flow z challenge + RSA-OAEP, parsowanie FA(2)/FA(3), refresh tokenów, rate limiting) oraz reconcyliacja faktur z wyciągami bankowymi (6-stopniowy pipeline dopasowujący KSeF ↔ MT940/mBank/ING/PKO BP/Santander).

Jako jeden z pierwszych SDK-ów do polskiej e-faktury Ksefnik wystawia również Model Context Protocol server — dzięki czemu możesz rozmawiać z KSeF-em z poziomu Claude Desktop, Cursora, Continue albo dowolnego innego klienta MCP. Pobranie faktur kosztowych za marzec, import wyciągu z ING i uruchomienie reconcyliacji sprowadza się do jednego zdania w czacie z AI.

Projekt jest na wczesnym etapie rozwoju — API może się zmieniać między wersjami 0.x. Od 1.0 obowiązuje semver.

Funkcje

Reconciliation Engine

Automatyczne dopasowywanie faktur KSeF do przelewow bankowych w 6 krokach: numer KSeF, dokladne dopasowanie NIP + kwota, numer faktury w tytule przelewu, przyblizone dopasowanie nazwy (fuzzy matching), platnosci czesciowe, dopasowanie bliskosci. Dokumentacja →

Bank Parsers

Import wyciagow z polskich bankow: MT940 (standard), CSV z mBank, ING, PKO BP, Santander. Automatyczna detekcja formatu pliku. Ekstrakcja NIP z tytulow przelewow. Dokumentacja →

HTTP Adapter (@ksefnik/http)

Produkcyjny klient HTTP do KSeF 2.0 (api.ksef.mf.gov.pl). Pelny flow uwierzytelnienia (challenge + RSA-OAEP), pobieranie metadanych faktur, parsowanie FA(2)/FA(3) XML, ekstrakcja kwot brutto. Gotowy do podpiecia pod createKsefnik() przez createHttpAdapter({ nip, token, environment, publicKeyPem }). Szczegoly: packages/http/README.md. Dokumentacja →

KSeF Simulator

Lokalny mock serwer KSeF do testow offline. Deterministyczny, bez polaczenia z Ministerstwem Finansow. Gotowe scenariusze: happy-path, timeout, odrzucenie faktury, wygasniecie sesji. Dokumentacja →

MCP Server

Model Context Protocol server (9 narzedzi) do integracji z Claude i innymi asystentami AI. Reconcyliacja, import wyciagow i zapytania o faktury bezposrednio z poziomu AI. Dokumentacja →

Walidacja faktur

Walidacja faktur przed wyslaniem do KSeF. Reguly biznesowe Ministerstwa Finansow z czytelnymi komunikatami bledow po polsku. Dokumentacja →

Type-Safe SDK

Pelne typy TypeScript wygenerowane z oficjalnych schematow XSD KSeF. Bledy wychwytywane na etapie kompilacji, a nie w runtime.

Instalacja

Wymagania: Node.js 22+, pnpm 9+

npm install @ksefnik/core @ksefnik/http
# lub
pnpm add @ksefnik/core @ksefnik/http

• @ksefnik/core — reconcyliacja, parsery bankow, walidacja (baza)
• @ksefnik/http — produkcyjny klient HTTP do KSeF 2.0 (wymagane do produkcji)
• @ksefnik/simulator — mock KSeF do testow offline (devDep)

npm install --save-dev @ksefnik/simulator

Konfiguracja HTTP adaptera

import { createKsefnik } from '@ksefnik/core'
import { createHttpAdapter } from '@ksefnik/http'
import { readFileSync } from 'node:fs'

const adapter = createHttpAdapter({
  nip: '7010002137',
  token: process.env.KSEF_TOKEN!,
  environment: 'production',
  publicKeyPem: readFileSync('./ksef-public-key.pem', 'utf8'),
})

const ksef = createKsefnik({
  config: { nip: '7010002137', environment: 'production', token: process.env.KSEF_TOKEN! },
  adapter,
})

await adapter.initSession?.()
const invoices = await ksef.invoices.fetch({ from: '2026-03-01', to: '2026-03-31' })
await adapter.closeSession?.()

Szybki start

Pelny przewodnik krok po kroku: docs.ksefnik.pl/wprowadzenie/szybki-start

import { createKsefnik } from '@ksefnik/core'

const ksef = createKsefnik({
  nip: '1234567890',
  environment: 'test',
  token: process.env.KSEF_TOKEN
})

// Pobierz faktury z KSeF
const invoices = await ksef.invoices.fetch({
  dateFrom: '2026-03-01',
  dateTo: '2026-03-31'
})

// Zaimportuj wyciag bankowy
const transactions = await ksef.bank.import('./wyciag.mt940')

// Uruchom reconcyliacje
const report = await ksef.reconciliation.run({ invoices, transactions })

console.log(`Dopasowane: ${report.matched.length}`)
console.log(`Niedopasowane faktury: ${report.unmatchedInvoices.length}`)
console.log(`Niedopasowane przelewy: ${report.unmatchedTransactions.length}`)

Architektura

Szczegolowy opis architektury monorepo: docs.ksefnik.pl/zaawansowane/architektura-monorepo

Ksefnik stosuje podejscie SDK-first -- cala logika biznesowa znajduje sie w pakiecie core, a pozostale pakiety (CLI, MCP server) sa cienkimi wrapperami, ktore z niego korzystaja.

ksefnik/
  packages/
    shared/       @ksefnik/shared      Typy Zod, interfejsy, plugin system
    core/         @ksefnik/core        Reconciliation engine, bank parsers, KSeF adapter
    http/         @ksefnik/http        Produkcyjny klient HTTP do KSeF API v2
    simulator/    @ksefnik/simulator   Offline KSeF test harness
    mcp/          @ksefnik/mcp         MCP server (wrapper na core)
    cli/          @ksefnik/cli         CLI (Commander.js), standalone binary via bun compile

Pakiet	Opis
@ksefnik/shared	Wspoldzielone typy Zod, interfejsy i plugin system
@ksefnik/core	Glowna logika: reconciliation engine, bank parsers, adapter KSeF
@ksefnik/http	Produkcyjny klient HTTP do KSeF 2.0 (auth RSA-OAEP, sesje, pobieranie faktur)
@ksefnik/simulator	Lokalny mock serwer KSeF do testow offline
@ksefnik/mcp	Model Context Protocol server -- integracja z AI
@ksefnik/cli	Interfejs wiersza polecen, kompilacja do standalone binary

MCP Server

MCP server udostępnia 9 narzędzi (reconcyliacja, import wyciągów, zapytania o faktury, walidacja, wysyłka, UPO) bezpośrednio z poziomu Claude Desktop, Cursor, Claude Code i innych klientów MCP.

Claude Desktop

Dodaj do claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json na macOS):

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "7010002137",
        "KSEF_TOKEN": "twoj-token-ksef",
        "KSEF_ENV": "test"
      }
    }
  }
}

Cursor

Dodaj do .cursor/mcp.json w katalogu projektu:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "7010002137",
        "KSEF_TOKEN": "twoj-token-ksef",
        "KSEF_ENV": "test"
      }
    }
  }
}

Claude Code

claude mcp add ksefnik -- npx -y @ksefnik/mcp

Uruchomienie ręczne

npx @ksefnik/mcp

Dostępne narzędzia

Narzędzie	Opis
sync-invoices	Pobierz faktury z KSeF
query-invoices	Wyszukaj faktury
import-bank	Importuj wyciąg bankowy
reconcile	Uruchom reconcyliację
get-unmatched	Pokaż niedopasowane pozycje
send-invoice	Wyślij fakturę do KSeF
validate-invoice	Waliduj fakturę
confirm-match	Potwierdź dopasowanie
get-upo	Sprawdź status UPO (potwierdzenie odbioru)

Stack technologiczny

Technologia	Zastosowanie
TypeScript (strict)	Jezyk programowania
Node.js 22	Srodowisko uruchomieniowe
pnpm	Menedzer pakietow, workspace monorepo
Zod	Walidacja danych i definicja schematow
Vitest	Framework testowy
Commander.js	CLI framework
@clack/prompts	Interaktywne prompty CLI
@modelcontextprotocol/sdk	Implementacja MCP server
fuzzball	Fuzzy string matching
mt940js	Parser formatu MT940
bun	Kompilacja CLI do standalone binary

Rozwoj

Uruchomienie lokalne

git clone https://github.com/CodeFormers-it/ksefnik.git
cd ksefnik
pnpm install
pnpm build

Testy

pnpm test           # uruchom wszystkie testy
pnpm test:watch     # tryb watch

Wytyczne dla Pull Requestow

Pelny przewodnik dla kontrybutorów: docs.ksefnik.pl/zaawansowane/contributing

1. Stworz branch z opisowa nazwa (feat/partial-payments, fix/mt940-parser).
2. Upewnij sie, ze wszystkie testy przechodza (pnpm test).
3. Dodaj testy dla nowej funkcjonalnosci.
4. Opisz zmiany w PR -- co, dlaczego i jak przetestowac.

Zapraszamy do zglaszania Issues i Pull Requestow. Projekt jest na wczesnym etapie, wiec kazdego rodzaju wklad jest mile widziany.

Często zadawane pytania

Jak pobrać faktury z KSeF w Node.js albo TypeScript?

Zainstaluj @ksefnik/core i @ksefnik/http, skonfiguruj createHttpAdapter z tokenem KSeF i kluczem publicznym MF, i woła ksef.invoices.fetch({ from, to }). Pełen przykład w sekcji Szybki start. Ksefnik jest w tej chwili jedynym produkcyjnym KSeF SDK dla TypeScript / Node.js z pełnym pokryciem flow uwierzytelnienia KSeF 2.0.

Czy Ksefnik wspiera KSeF 2.0 (obowiązkowe API od 2026-02-01)?

Tak. Pakiet @ksefnik/http rozmawia bezpośrednio z api.ksef.mf.gov.pl/v2, implementuje pełen flow uwierzytelnienia (challenge + RSA-OAEP SHA-256, redeem, refresh) i parsuje faktury w formacie FA(2)/FA(3). Typy są generowane z oficjalnego OpenAPI MF, więc przy każdej zmianie kontraktu w MF masz breaking change na etapie kompilacji TypeScript.

Jak zintegrować KSeF z Claude Desktop, Cursorem albo innym agentem AI?

Ksefnik wystawia pełny serwer Model Context Protocol (@ksefnik/mcp) z 8 narzędziami: pobieranie faktur z KSeF, import wyciągów bankowych, reconcyliacja, zapytania o niedopasowane pozycje, ręczne potwierdzanie matchów, walidacja i wysyłka. Konfiguracja Claude Desktop to 5 linii JSON-a w claude_desktop_config.json — szczegóły w sekcji MCP Server i w @ksefnik/mcp. Jeżeli szukasz KSeF MCP server albo KSeF Claude AI integration — to jest to.

Jak zautomatyzować dopasowanie faktur KSeF do wyciągu bankowego?

Silnik @ksefnik/core odpala 6-stopniowy pipeline reconcyliacji: referencja KSeF → NIP + dokładna kwota → numer faktury w tytule przelewu → fuzzy matching nazwy kontrahenta → płatności częściowe → proximity. Każdy match ma score, strategy i confidence, więc automatycznie wiesz, które dopasowania można zatwierdzić bez oglądania, a które skierować do ręcznej weryfikacji. Wspierane formaty wyciągów: MT940 (SWIFT, wszystkie polskie banki), mBank CSV, ING CSV, PKO BP CSV, Santander CSV.

Czy mogę testować integrację z KSeF offline, bez dostępu do api-test.ksef.mf.gov.pl?

Tak — @ksefnik/simulator to deterministyczny offline mock KSeF z gotowymi scenariuszami testowymi (happy-path, timeout, wygasła sesja, błąd walidacji NIP, opóźnione UPO). Implementuje dokładnie ten sam interfejs co @ksefnik/http, więc kod produkcyjny nie wie, że odpowiada mu mock. Idealny do CI w GitHub Actions — bez tokenów, bez sekretów, bez zależności od dostępności serwerów MF.

Szukam biblioteki do KSeF w Pythonie — czy jest alternatywa w TypeScript?

Ksefnik jest natywnym KSeF SDK w TypeScript — działa w Node.js 22+, Next.js API routes, serverless (Vercel Functions, Lambda, Cloudflare Workers), długo żyjących workerach, CLI i jako MCP server dla agentów AI. Kwoty są trzymane jako integer grosze (bez floatów), modele domenowe są schematami Zod, kryptografia idzie przez node:crypto + webcrypto.subtle (zero zależności kryptograficznych trzecich).

Jakie środowiska KSeF wspiera?

Środowisko	Bazowy URL
production	https://api.ksef.mf.gov.pl/v2
demo	https://api-demo.ksef.mf.gov.pl/v2
test	https://api-test.ksef.mf.gov.pl/v2

Środowisko ustawiasz flagą --env w CLI albo polem environment w createHttpAdapter. Domyślnie test, żeby nic nie wyszło na produkcję przypadkiem.

Czy Ksefnik obsługuje wysyłkę faktur do KSeF, czy tylko odczyt?

W obecnej wersji MVP pełna wysyłka (asynchroniczny POST /invoices/exports + polling + UPO) jest jeszcze niepełna — sendInvoice w @ksefnik/http jest stubem. Pełne wsparcie wysyłki wchodzi w v0.1. Pobieranie faktur, reconcyliacja, walidacja i integracja MCP działają produkcyjnie już dziś.

Licencja

MIT — darmowe dla wszystkich, do dowolnego zastosowania. Szczegóły w pliku LICENSE.

---

Stworzone przez CodeFormers.it -- software house specjalizujacy sie w TypeScript, automatyzacji i integracji systemow.

codeformers.it  |  Wycen projekt w 60 sekund