# Ksefnik > KSeF SDK for TypeScript/Node.js — invoice reconciliation with bank statements (MT940, mBank, ING, PKO, Santander), production KSeF 2.0 HTTP client, MCP server for Claude and Cursor. Open-source, MIT. - **Type:** MCP server - **Install:** `agentstack add mcp-codeformers-it-ksefnik` - **Verified:** Pending review - **Seller:** [CodeFormers-it](https://agentstack.voostack.com/s/codeformers-it) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [CodeFormers-it](https://github.com/CodeFormers-it) - **Source:** https://github.com/CodeFormers-it/ksefnik ## Install ```sh agentstack add mcp-codeformers-it-ksefnik ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About     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](https://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 →](https://docs.ksefnik.pl/silnik-uzgadniania/jak-dziala-pipeline/) ### 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 →](https://docs.ksefnik.pl/parsery-bankowe/obslugiwane-formaty/) ### 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](packages/http/README.md). [Dokumentacja →](https://docs.ksefnik.pl/http/przeglad/) ### 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 →](https://docs.ksefnik.pl/symulator/happy-path/) ### 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 →](https://docs.ksefnik.pl/mcp/konfiguracja/) ### Walidacja faktur Walidacja faktur przed wyslaniem do KSeF. Reguly biznesowe Ministerstwa Finansow z czytelnymi komunikatami bledow po polsku. [Dokumentacja →](https://docs.ksefnik.pl/walidacja/mechanizm/) ### 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+ ```bash 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) ```bash npm install --save-dev @ksefnik/simulator ``` ### Konfiguracja HTTP adaptera ```ts 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](https://docs.ksefnik.pl/wprowadzenie/szybki-start/) ```typescript 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](https://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): ```json { "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: ```json { "mcpServers": { "ksefnik": { "command": "npx", "args": ["-y", "@ksefnik/mcp"], "env": { "KSEF_NIP": "7010002137", "KSEF_TOKEN": "twoj-token-ksef", "KSEF_ENV": "test" } } } } ``` ### Claude Code ```bash claude mcp add ksefnik -- npx -y @ksefnik/mcp ``` ### Uruchomienie ręczne ```bash 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 ```bash git clone https://github.com/CodeFormers-it/ksefnik.git cd ksefnik pnpm install pnpm build ``` ### Testy ```bash pnpm test # uruchom wszystkie testy pnpm test:watch # tryb watch ``` ### Wytyczne dla Pull Requestow > Pelny przewodnik dla kontrybutorów: [docs.ksefnik.pl/zaawansowane/contributing](https://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](#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](#mcp-server) i w [`@ksefnik/mcp`](packages/mcp/README.md). 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](LICENSE). --- Stworzone przez CodeFormers.it -- software house specjalizujacy sie w TypeScript, automatyzacji i integracji systemow. codeformers.it  |  Wycen projekt w 60 sekund ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [CodeFormers-it](https://github.com/CodeFormers-it) - **Source:** [CodeFormers-it/ksefnik](https://github.com/CodeFormers-it/ksefnik) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-codeformers-it-ksefnik - Seller: https://agentstack.voostack.com/s/codeformers-it - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.