@ksefnik/cli — KSeF CLI dla TypeScript / Node.js (z MCP serverem dla Claude)

Wiersz poleceń do Krajowego Systemu e-Faktur (KSeF 2.0) — pobieranie faktur, import wyciągów bankowych (MT940, mBank, ING, PKO BP, Santander), reconcyliacja faktur z przelewami, walidacja przed wysyłką i uruchamianie serwera Model Context Protocol dla Claude Desktop i Cursora. Część Ksefnika — otwartego KSeF SDK w TypeScript / Node.js. Jeden komfortowy binarny interfejs dla developerów, zespołów fintech, automatyzacji w CI / cron i agentów AI.

Znany również jako: KSeF CLI, ksef command line, e-faktura CLI, Polish e-Invoice CLI, KSeF MCP launcher. Dokumentacja CLI →

npx @ksefnik/cli --help

Instalacja

# globalnie
npm install -g @ksefnik/cli

# albo jednorazowo, bez instalacji
npx @ksefnik/cli <komenda>

Wymaga Node.js 22+.

Konfiguracja

CLI czyta parametry z trzech miejsc (priorytet od najwyższego):

1. flagi na linii komend — --nip, --env, --token, --public-key
2. zmienne środowiskowe — KSEF_NIP, KSEF_TOKEN, KSEFNIK_ENV, KSEFNIK_ADAPTER, KSEF_PUBLIC_KEY_PATH
3. plik .env w bieżącym katalogu (przez --env-file)

Rekomendowane — .env w katalogu projektu:

# .env
KSEF_NIP=7010002137
KSEF_TOKEN=twój-token-z-portalu-MF
KSEFNIK_ENV=production        # production | demo | test
KSEFNIK_ADAPTER=http          # http (produkcja) | simulator (testy)
KSEF_PUBLIC_KEY_PATH=./mf-public.pem

Środowiska KSeF:

| --env | 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 |

Domyślnie test — czyli CLI z nieskonfigurowanym środowiskiem nie wyśle Ci nic przypadkiem na produkcję. Żeby ruszyć produkcję, musisz świadomie ustawić KSEFNIK_ENV=production.

Komendy

ksefnik fetch — pobierz faktury z KSeF

ksefnik fetch --from 2026-03-01 --to 2026-03-31 --format table

| Flaga | Opis | |---|---| | --from <date> | Data początkowa (YYYY-MM-DD), wymagane | | --to <date> | Data końcowa (YYYY-MM-DD), wymagane | | --format <fmt> | json (default) albo table |

Pod spodem woła ksef.invoices.fetch() z @ksefnik/core przez adapter HTTP. Obsługuje retry, 429, refresh tokenów, cache klucza publicznego MF.

ksefnik bank import <plik> — zaimportuj wyciąg bankowy

ksefnik bank import ./wyciag.mt940
ksefnik bank import ./export-mbank.csv --format table

Auto-detekcja formatu: MT940, mBank CSV, ING CSV, PKO BP CSV, Santander CSV. Wypisuje liczbę wczytanych transakcji i zrzuca je w wybranym formacie. Kwoty są normalizowane do groszy (int) — jeżeli widzisz 123.45, to jest to 12345 groszy pod spodem.

ksefnik reconcile --bank <plik> — odpal reconcyliację

ksefnik reconcile --bank ./wyciag.mt940 --format table

Uruchamia 6-stopniowy pipeline z @ksefnik/core:

1. referencja KSeF w tytule przelewu
2. NIP + dokładna kwota
3. numer faktury w tytule
4. fuzzy matching nazwy kontrahenta
5. płatności częściowe
6. proximity (NIP + kwota ±tolerancja + data ±N dni)

Na wyjściu dostajesz pełny raport: dopasowane (z score i strategy), niedopasowane faktury, niedopasowane przelewy, średnią pewność. W --format table od razu czytelnie w terminalu, w --format json gotowe do wpięcia w pipeline w CI / GitHub Actions / cron.

ksefnik validate <plik> — zwaliduj fakturę(y) przed wysłaniem

ksefnik validate ./faktura.json
ksefnik validate ./faktury.json --format table

Wczytuje pojedynczą fakturę albo tablicę faktur z pliku JSON, odpala wszystkie reguły walidacji z @ksefnik/core i raportuje. Każdy błąd ma kod, severity i human-readable message po polsku — nadaje się bezpośrednio do wyświetlenia użytkownikowi. Do użycia jako pre-send gate przed ksefnik send.

Testowane reguły obejmują m.in.: format NIP (sprzedawca + nabywca), poprawność waluty (ISO 4217), dodatnie kwoty, spójność netto+VAT=brutto, kolejność dat, poprawne stawki VAT (PL: 0/5/8/23/zw/np/oo), duplikaty, długość opisów, format numeru faktury.

ksefnik send <plik.xml> — wyślij fakturę do KSeF

ksefnik send ./faktura.xml

MVP: sendInvoice w @ksefnik/http jest w tym momencie stubem. Komenda wywoła adapter, ale na realny KSeF wrzuci rzut "not implemented". W pełnym asynchronicznym flow (POST /invoices/exports + polling + UPO) wejdzie w v0.1.

ksefnik mcp — uruchom serwer MCP dla Claude

Pelna konfiguracja MCP: docs.ksefnik.pl/mcp/konfiguracja

ksefnik mcp

To jest ta komenda, której używa Twoja konfiguracja Claude Desktop w claude_desktop_config.json:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/cli", "mcp"],
      "env": {
        "KSEF_NIP": "7010002137",
        "KSEF_TOKEN": "...",
        "KSEFNIK_ENV": "production",
        "KSEF_PUBLIC_KEY_PATH": "/abs/path/do/mf-public.pem"
      }
    }
  }
}

Serwer używa StdioServerTransport z oficjalnego @modelcontextprotocol/sdk i wystawia 9 narzędzi (sync-invoices, query-invoices, import-bank, reconcile, get-unmatched, confirm-match, validate-invoice, send-invoice, get-upo). Szczegóły w @ksefnik/mcp.

Flagi globalne

Wszystkie komendy akceptują flagi globalne programu:

| Flaga | Opis | |---|---| | --nip <nip> | NIP firmy (nadpisuje KSEF_NIP) | | --env <env> | production / demo / test (nadpisuje KSEFNIK_ENV) | | --token <token> | Token KSeF (nadpisuje KSEF_TOKEN) | | --adapter <kind> | http (default) / simulator (offline, do testów) | | --public-key <pathOrPem> | Ścieżka do PEM klucza publicznego MF albo PEM inline | | --debug | Rozszerzone logi (m.in. żądania HTTP, retry, stan sesji) |

Scenariusze użycia

Codzienna reconcyliacja w cronie

#!/usr/bin/env bash
set -euo pipefail

export KSEF_NIP=7010002137
export KSEF_TOKEN="$(op read 'op://vault/ksef/token')"   # np. 1Password CLI
export KSEFNIK_ENV=production
export KSEF_PUBLIC_KEY_PATH=/etc/ksefnik/mf-public.pem

# 1. Pobierz wczorajsze faktury kosztowe
ksefnik fetch --from "$(date -v-1d +%F)" --to "$(date -v-1d +%F)" > /tmp/invoices.json

# 2. Ściągnij wyciąg z bankiera (np. przez ich API albo scp)
# ...

# 3. Reconcyliacja
ksefnik reconcile --bank /tmp/wyciag.mt940 --format json > /tmp/report.json

# 4. Wyślij raport na Slack, do Linear, do bazy, gdziekolwiek

CI pipeline — walidacja faktur przed wysłaniem

# .github/workflows/validate.yml
- run: npx @ksefnik/cli validate ./invoices/*.json --format json

Testowanie offline z simulatorem

KSEFNIK_ADAPTER=simulator ksefnik fetch --from 2026-03-01 --to 2026-03-31

Zero requestów do produkcji, zero potrzeby tokenu — pipeline wciąż ten sam.

Kompilacja do standalone binary

Dla dystrybucji bez node_modules:

pnpm --filter @ksefnik/cli build
bun build --compile ./apps/build/dist/main.js --outfile ksefnik
./ksefnik --help

Efekt: pojedynczy plik wykonywalny, bez potrzeby instalowania Node.js na maszynie docelowej. Przydaje się, kiedy wrzucasz Ksefnika do firmowego image'u Dockerowego albo do niestandardowego środowiska, gdzie nie chcesz ciągnąć npm.

Powiązane pakiety

• @ksefnik/core — silnik, który CLI opakowuje
• @ksefnik/http — produkcyjny adapter HTTP
• @ksefnik/simulator — mock do trybu offline
• @ksefnik/mcp — serwer MCP uruchamiany komendą ksefnik mcp

Licencja

MIT. Część monorepo ksefnik. Ksefnik jest rozwijany przez CodeFormers.it — budujemy integracje KSeF, automatyzacje w n8n, dedykowane CLI-boty i narzędzia backoffice w TypeScript. Jeżeli Twój zespół potrzebuje CLI skrojonego pod Twój workflow księgowy (np. własne komendy eksportu do ERP, własny format wyciągu, integracja z Twoim systemem magazynowym) — napisz do nas.