ksef MCP

ksef-mcp

](https://www.npmjs.com/package/ksef-mcp)   ](https://nodejs.org) 

Pierwszy publiczny MCP server do Krajowego Systemu e-Faktur (KSeF) — API v2.

Uwierzytelnianie (JWT), wystawianie, walidacja i pobieranie e-faktur przez AI. Kompatybilny z Claude Desktop, Claude Code i ChatGPT.

KSeF API v2 (2026) — nowe endpointy, JWT Bearer auth, osobne sesje online/batch. Dokumentacja API: api.ksef.mf.gov.pl/docs/v2 | Dokumentacja integracji:

Funkcje

Narzedzia (30 toolow)

Instalacja

Z repozytorium (development)

git clone https://github.com/gacabartosz/ksef-mcp.git
cd ksef-mcp
npm install
npm run build

Z npm (po publikacji)

npm install -g ksef-mcp

Konfiguracja

Skopiuj .env.example do .env i uzupelnij:

cp .env.example .env

Zmienne srodowiskowe

Token KSeF — jak uzyskac

To jest najwazniejsza sekcja jesli chcesz przetestowac integracje z KSeF.

Srodowiska KSeF 2.0

Portal informacyjny: ksef.podatki.gov.pl

Jak uzyskac token KSeF

Token KSeF mozna wygenerowac w Aplikacji Podatnika lub przez API.

Sposob 1: Przez Aplikacje Podatnika (najlatwiejszy)

1. Wejdz na Aplikacje Podatnika:

- Produkcja: ap.ksef.mf.gov.pl - Test: ap-test.ksef.mf.gov.pl - Demo: ap-demo.ksef.mf.gov.pl

1. Zaloguj sie Profilem Zaufanym, podpisem kwalifikowanym lub e-dowodem
2. Przejdz do sekcji Tokeny i wygeneruj nowy token:

- Wybierz uprawnienia: odczyt faktur, wystawianie faktur, itp. - Skopiuj token (wyswietlany tylko raz!)

1. Wklej token do konfiguracji MCP (KSEF_TOKEN)

Generowanie tokenow w Aplikacji Podatnika dostepne do 31 grudnia 2026 r.

Sposob 2: Przez API (po uwierzytelnieniu XAdES)

1. Uwierzytelnij sie podpisem elektronicznym: uwierzytelnianie.md
2. Wywolaj POST /tokens z uprawnieniami i opisem
3. Dostepne uprawnienia: InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage, SubunitManage, EnforcementOperations, Introspection

Dokumentacja tokenow: tokeny-ksef.md

Przeplyw uwierzytelniania (API v2)

Gdy masz token, ksef-mcp automatycznie wykonuje caly flow:

1. POST /auth/challenge              → { challenge, timestamp, timestampMs }
2. POST /auth/ksef-token             → zaszyfruj token|timestampMs kluczem RSA-OAEP
                                       → { authenticationToken (JWT), referenceNumber }
3. GET  /auth/{referenceNumber}      → sprawdz status (polling)
4. POST /auth/token/redeem           → Bearer: authToken → { accessToken, refreshToken }
5. Uzyj: Authorization: Bearer {accessToken} do wszystkich wywolan API
6. POST /auth/token/refresh          → Bearer: refreshToken → nowy accessToken

Szczegoly: Proces uwierzytelniania KSeF 2.0

Przyklad konfiguracji

KSEF_ENV=prod
KSEF_NIP=5993112591
KSEF_TOKEN=twoj-wygenerowany-token-ksef

Wazne uwagi

• Wymagany polski IP — srodowiska KSeF sa chronione przez WAF i wymagaja polskiego adresu IP
• Produkcja vs Test — na produkcji faktury maja moc prawna! Do testow uzywaj srodowiska TEST
• Test — mozna uzyc fikcyjnych danych, dane sa okresowo usuwane
• Demo — logowanie prawdziwymi danymi (NIP z rejestru), ale faktury bez skutkow prawnych
• Klucze publiczne MF — pobierane automatycznie z GET /security/public-key-certificates
• Mozesz przelaczac srodowisko w runtime toolem ksef_env_set (bez restartu MCP)

Praca bez dostepu do KSeF (tryb offline)

Wiele narzedzi dziala bez polaczenia z API KSeF:

Mozesz wiec tworzyc, walidowac i przegladac faktury bez tokena i dostepu do API.

Uzycie z Claude Desktop

Dodaj do ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) lub %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ksef": {
      "command": "node",
      "args": ["/sciezka/do/ksef-mcp/dist/index.js"],
      "env": {
        "KSEF_ENV": "test",
        "KSEF_NIP": "0000000001",
        "KSEF_TOKEN": "twoj-token-ksef"
      }
    }
  }
}

Po zapisaniu pliku zrestartuj Claude Desktop. Narzedzia KSeF pojawia sie w panelu bocznym.

Uzycie z Claude Code

Dodaj do ~/.claude.json (scope: user):

{
  "mcpServers": {
    "ksef": {
      "command": "node",
      "args": ["/sciezka/do/ksef-mcp/dist/index.js"],
      "env": {
        "KSEF_ENV": "test",
        "KSEF_NIP": "0000000001",
        "KSEF_TOKEN": "twoj-token-ksef"
      }
    }
  }
}

Lub w .mcp.json w katalogu projektu (scope: project):

{
  "mcpServers": {
    "ksef": {
      "command": "node",
      "args": ["/sciezka/do/ksef-mcp/dist/index.js"],
      "env": {
        "KSEF_ENV": "test",
        "KSEF_NIP": "0000000001",
        "KSEF_TOKEN": "twoj-token-ksef"
      }
    }
  }
}

Uzycie z claude.ai (Remote Connector)

ksef-mcp mozna podlaczyc jako remote MCP connector w claude.ai:

1. Wejdz na claude.ai → Settings → Connectors → Add custom connector
2. Wpisz:

- Name: KSeF - Remote MCP server URL: https://bartoszgaca.pl/ksef/mcp

1. Kliknij Add

Serwer odpowiada na Streamable HTTP transport (POST/GET/DELETE na /mcp).

Uwaga: Tokeny KSeF sa przechowywane server-side — claude.ai nie ma dostepu do sekretow.

Self-hosting HTTP transport

Mozesz postawic wlasna instancje:

git clone https://github.com/gacabartosz/ksef-mcp.git
cd ksef-mcp && npm install && npm run build

# Uruchom HTTP server
MCP_PORT=3400 KSEF_ENV=test node dist/http.js

Nginx reverse proxy:

location /ksef/ {
    proxy_pass http://127.0.0.1:3400/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
}

Przeplyw wysylki faktury

Pelny przeplyw od szkicu do wysylki:

1. ksef_auth_init        → Uwierzytelnij (challenge → ksef-token → redeem → JWT)
2. ksef_draft_create     → Utworz szkic faktury
3. ksef_draft_validate   → Zwaliduj wg regul FA(3)
4. ksef_draft_lock       → Zablokuj i oblicz hash XML
5. ksef_approval_request → Zadaj zatwierdzenia
6. ksef_approval_confirm → Potwierdz (lub auto jesli KSEF_APPROVAL_MODE=auto)
7. ksef_send_invoice     → Auto-otwiera sesje online, szyfruje AES-256-CBC, wysyla
8. ksef_invoice_status   → Sprawdz status przetwarzania (sessionRef + invoiceRef)
9. ksef_audit_log        → Przejrzyj log audytowy

Przeplyw korekty faktury

1. ksef_correction_create → Sklonuj wyslana fakture jako korekte (z powodem)
2. ksef_draft_update      → Zmodyfikuj pozycje korekty
3. (dalej standardowy przeplyw: validate → lock → approval → send)

Przeplyw batch (wysylka zbiorcza, API v2)

1. ksef_batch_open        → Otworz sesje batch (podaj file hash + parts) → pre-signed URLs
2. ksef_batch_send_part   → Upload czesci na pre-signed URLs
3. ksef_batch_close       → Zamknij sesje batch
4. ksef_batch_status      → Sprawdz status przetwarzania (GET /sessions/{ref})

Tryb automatycznego zatwierdzania

Ustaw KSEF_APPROVAL_MODE=auto aby pominac reczne zatwierdzanie. W tym trybie ksef_approval_request automatycznie potwierdza approval.

Uwaga: Tryb automatyczny jest wygodny do testow, ale w produkcji zalecany jest tryb manual dla pelnej kontroli.

Testowanie narzedzi (stdio)

Mozesz testowac narzedzia bezposrednio przez stdin/stdout:

Lista narzedzi

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  KSEF_NIP=0000000001 node dist/index.js 2>/dev/null | jq .

Informacje o srodowisku

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ksef_env_info","arguments":{}}}' | \
  KSEF_NIP=0000000001 KSEF_ENV=test node dist/index.js 2>/dev/null | jq .

Utworzenie szkicu faktury

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ksef_draft_create","arguments":{"sellerNip":"0000000001","sellerName":"Firma Test Sp. z o.o.","sellerAddress":"ul. Testowa 1, 00-001 Warszawa","buyerNip":"9999999999","buyerName":"Klient Test S.A.","buyerAddress":"ul. Przykladowa 10, 00-002 Krakow","invoiceNumber":"FV/2026/001","issueDate":"2026-03-08","sellDate":"2026-03-08","currency":"PLN","items":[{"name":"Usluga programistyczna","quantity":1,"unitPrice":10000,"vatRate":23,"unit":"szt"}]}}}' | \
  KSEF_NIP=0000000001 node dist/index.js 2>/dev/null | jq .

Walidacja szkicu

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ksef_draft_validate","arguments":{"id":"ID-DRAFTU-Z-KROKU-WYZEJ"}}}' | \
  KSEF_NIP=0000000001 node dist/index.js 2>/dev/null | jq .

Rate limiting

Wbudowany rate limiter chroni przed przekroczeniem limitow API KSeF:

• 5 zapytan/sekunde (domyslnie)
• 200 zapytan/minute (domyslnie)
• 1000 zapytan/godzine (domyslnie)

Limity mozna dostosowac zmiennymi srodowiskowymi:

KSEF_RATE_LIMIT_PER_SECOND=10
KSEF_RATE_LIMIT_PER_MINUTE=300
KSEF_RATE_LIMIT_PER_HOUR=2000

Dodatkowo:

• Odpowiedz 429 (Too Many Requests) — automatyczne odczekanie wg naglowka Retry-After i ponowienie
• Bledy 500/502/503 — automatyczne ponowienie z exponential backoff (max 3 proby)
• Bledy 400/401/403/440 — brak ponowien (bledy klienta)

Bezpieczenstwo

• Tokeny i klucze nigdy nie sa przekazywane do modelu AI — pozostaja w srodowisku serwera MCP
• NIP-y sa maskowane w logach (123***90)
• NIP-y w audit logu sa hashowane SHA-256
• Wszystkie logi ida na stderr (stdout zarezerwowany dla protokolu MCP)
• Sesja zapisywana z uprawnieniami 0600
• Dwufazowa wysylka — faktura musi byc zwalidowana, zablokowana i zatwierdzona przed wyslaniem
• Hash XML — weryfikowany na kazdym etapie (lock → approval → send)
• Approval TTL — zatwierdzenie wygasa po 15 minutach
• Audit trail — kazda operacja jest logowana w formacie JSONL

Srodowiska KSeF 2.0

Portal informacyjny: ksef.podatki.gov.pl | Infolinia: 22 330 03 30 (pn-pt 8:00-18:00)

Roadmap

• [x] Sprint 1: Uwierzytelnianie + odczyt faktur (auth, query, session)
• [x] Sprint 2: Kryptografia + szkice faktur + walidacja FA(3)
• [x] Sprint 3: Dwufazowa wysylka + audit trail
• [x] Sprint 4: Korekty + batch + zarzadzanie tokenami
• [x] Sprint 5: Rate limiting + dokumentacja + token testowy
• [x] Sprint 6: Migracja na KSeF API v2 — nowe endpointy, JWT auth, sesje online/batch

Architektura

src/
  index.ts                  — Punkt wejscia MCP (Server + StdioTransport)
  mcp/
    registry.ts             — Rejestr narzedzi (registerTool, collectAll, dispatch)
    auth-tools.ts           — Narzedzia auth (4)
    query-tools.ts          — Narzedzia query (5)
    draft-tools.ts          — Narzedzia draft (7)
    send-tools.ts           — Narzedzia send (5)
    correction-tools.ts     — Narzedzia korekt (1)
    batch-tools.ts          — Narzedzia batch (4)
    token-tools.ts          — Narzedzia tokenow (4)
  domain/
    draft.ts                — CRUD szkicow, obliczanie sum (+ pola korekcyjne)
    validator.ts            — Walidacja FA(3): NIP, daty, stawki VAT, sumy
    xml-builder.ts          — Generator XML FA(3) (fast-xml-parser)
    approval.ts             — Dwufazowe zatwierdzanie (TTL 15min)
    audit.ts                — Append-only JSONL audit log
    correction.ts           — Faktury korygujace (klonowanie wyslanej faktury)
  infra/ksef/
    client.ts               — HTTP client (fetch + rate limit + retry + backoff)
    auth.ts                 — Auth v2 (challenge → ksef-token → redeem → JWT + refresh)
    crypto.ts               — RSA-OAEP, AES-256-CBC, SHA-256, public key certs
    session.ts              — Sesja online (open, send encrypted, close, status, UPO)
    batch.ts                — Sesja batch (open → pre-signed URLs, upload, close, status)
    token-client.ts         — Zarzadzanie tokenami KSeF (POST/GET/DELETE /tokens)
    rate-limiter.ts         — Token-bucket rate limiter
  utils/
    config.ts               — Zmienne srodowiskowe, URL-e, katalogi
    logger.ts               — Logi JSON na stderr z maskowaniem sekretow
    errors.ts               — toolResult/toolError, KsefApiError

Licencja

MIT -- zobacz LICENSE

Autor

Bartosz Gaca — bartoszgaca.pl |