Krótka odpowiedź: masz trzy drogi. Program do faktur z wbudowaną obsługą KSeF, własna integracja z API KSeF v2 albo gotowy serwer MCP, który podłącza KSeF do asystenta AI. Jeśli nie chcesz pisać integracji od zera, zacznij od środowiska TEST i serwera MCP: szkic, walidacja FA(3), zatwierdzenie, wysyłka.
Aktualizacja: 1 października 2026 r.
Poniżej porównanie tych trzech dróg, kroki dla wariantu z serwerem MCP i odpowiedzi na pytania, które słyszę najczęściej. Przykład opieram na ksef-mcp, otwartym serwerze MCP do KSeF, który zbudowałem i udostępniam na GitHubie. Nie jest jedynym takim narzędziem, więc piszę też, kiedy lepiej wybrać coś innego.
Trzy drogi do KSeF: porównanie
| Droga | Kiedy pasuje | Co musisz zrobić sam | Na co uważać |
|---|---|---|---|
| Program do faktur z obsługą KSeF | Wystawiasz faktury ręcznie, w jednym miejscu | Wybrać program, wygenerować token, wprowadzić faktury | Twój własny system (sklep, CRM, ERP) dalej musi jakoś przekazać dane do programu |
| Własna integracja z API KSeF v2 | Duży wolumen, faktury powstają automatycznie w Twoim systemie | Uwierzytelnianie tokenem i JWT, szyfrowanie, XML w formacie FA(3), sesje online i batch, odczyt statusów | Najwięcej pracy i utrzymania, każdą zmianę API wdrażasz u siebie |
| Serwer MCP do KSeF | Chcesz wystawiać, sprawdzać i pobierać faktury z poziomu Claude, przetestować obieg albo zrobić prototyp przed pełną integracją | Zainstalować serwer, wkleić token do konfiguracji, zatwierdzać wysyłki | To nie jest automatyczna integracja Twojego ERP. Człowiek zatwierdza wysyłkę, a model AI pracuje na narzędziach serwera |
Najważniejsza różnica: przy własnej integracji piszesz kod, który rozmawia z KSeF. Przy serwerze MCP ten kod już istnieje, a Ty mówisz asystentowi, co ma zrobić. Serwer MCP to po prostu zestaw narzędzi, które model AI może wywołać, tak jak człowiek klika przyciski w programie.
Co trzeba obsłużyć, pisząc integrację samodzielnie
Żeby było jasne, czego unikasz, wybierając gotowe narzędzie. Według dokumentacji API v2 sama autoryzacja to kilka kroków: pobranie wyzwania, zaszyfrowanie tokena kluczem publicznym Ministerstwa Finansów, sprawdzanie statusu, wymiana na token dostępu i jego odświeżanie. Do tego faktura musi pasować do schematu FA(3), bo inaczej KSeF ją odrzuci. Wysyłka idzie w szyfrowanej sesji, a numer KSeF i UPO odbierasz dopiero po przetworzeniu.
To wszystko da się napisać. Pytanie, czy musisz to robić, zanim w ogóle sprawdzisz, jak KSeF zachowuje się na Twoich fakturach.
Krok po kroku: KSeF przez serwer MCP
- Wybierz środowisko TEST. KSeF ma trzy środowiska. TEST służy do testów na fikcyjnych danych. W DEMO faktury też nie mają skutków prawnych. PROD to produkcja, gdzie faktura ma moc prawną. Zaczynaj zawsze od TEST.
- Wygeneruj token. W Aplikacji Podatnika danego środowiska zaloguj się Profilem Zaufanym, podpisem kwalifikowanym albo e-dowodem, przejdź do sekcji tokenów, wybierz uprawnienia i skopiuj token. Wyświetla się tylko raz.
- Zainstaluj serwer z repozytorium. Sklonuj github.com/gacabartosz/ksef-mcp, a potem uruchom
npm installinpm run build. Potrzebny jest Node.js w wersji 20 lub nowszej. Pakiet ksef-mcp na PyPI to inny projekt, a na npm ten serwer nie jest opublikowany, więc instaluj go z repozytorium. - Podłącz serwer do Claude. W Claude Desktop albo Claude Code dodajesz wpis
ksefw sekcjimcpServers, ze ścieżką dodist/index.jsi trzema zmiennymi:KSEF_ENV=test,KSEF_NIPiKSEF_TOKEN. - Utwórz i sprawdź szkic. Poproś o fakturę zwykłym zdaniem, z nabywcą, pozycjami i stawką VAT. Serwer tworzy szkic i waliduje go według reguł FA(3). Ten krok działa nawet bez połączenia z KSeF, więc możesz ćwiczyć na sucho.
- Zablokuj i zatwierdź. Zablokowany szkic dostaje skrót XML, który jest sprawdzany przy zatwierdzeniu i wysyłce. Zatwierdzasz sam, bo domyślny jest tryb ręczny.
- Wyślij i odbierz numer. Serwer loguje się do KSeF, otwiera sesję, szyfruje fakturę i ją wysyła. Status przetwarzania sprawdzasz w tej samej rozmowie, a na końcu dostajesz numer KSeF i UPO.
- Korekty i wysyłka zbiorcza. Korektę tworzysz z wysłanej faktury, z podanym powodem, i przechodzi ten sam obieg. Do większej liczby faktur jest sesja batch.
Gdy obieg działa na TEST, zmieniasz KSEF_ENV na prod i wklejasz token z produkcyjnej Aplikacji Podatnika. Wcześniej warto przejść przez DEMO.
Bezpieczeństwo i kontrola
- Token i klucze zostają po stronie serwera MCP. Model AI ich nie dostaje.
- Wysyłka jest dwufazowa: walidacja, blokada i zatwierdzenie muszą być przed wysłaniem.
- Zatwierdzenie wygasa po 15 minutach, a skrót XML pilnuje, żeby nie wyszła inna treść niż ta zatwierdzona.
- Każda operacja trafia do lokalnego logu audytowego, a NIP-y w logach są maskowane.
- Według README projektu połączenie z KSeF wymaga polskiego adresu IP, bo środowiska są chronione przez WAF. Jeśli pracujesz z zagranicy albo przez VPN, wysyłka może nie przejść.
Kiedy serwer MCP nie wystarczy
Jeśli Twój sklep albo system sprzedaży wystawia dużo faktur bez udziału człowieka, potrzebujesz integracji działającej w tle, a nie rozmowy z asystentem. Serwer MCP przydaje się wtedy na etapie testów: sprawdzasz na prawdziwych przypadkach, jak KSeF przyjmuje Twoje faktury, korekty i paczki, zanim zamówisz albo napiszesz docelowy moduł. Kod ksef-mcp jest otwarty na licencji MIT, więc widać w nim, jak rozwiązane są uwierzytelnianie, szyfrowanie i walidacja.
Jeśli faktury wystawia jedna osoba w jednym programie, najprostszy będzie program do faktur z obsługą KSeF. Serwer MCP ma sens, gdy chcesz pracować z fakturami z poziomu asystenta AI: wystawiać, wyszukiwać, pobierać XML i sprawdzać statusy w jednej rozmowie.
Projekt, na którym opieram ten opis
ksef-mcp to otwarty serwer MCP do KSeF API v2 i formatu FA(3). Ma 32 narzędzia: logowanie, szkice, walidację, wysyłkę, korekty, sesje batch, wyszukiwanie i pobieranie faktur. Opis obiegu jest w case study ksef-mcp, a instalacja w README na GitHubie. Jeśli zastanawiasz się, gdzie automatyzacja faktur daje największy zwrot, przeczytaj też AI w księgowości: koniec z ręcznym wprowadzaniem faktur.
Jeśli chcesz połączyć KSeF z własnym systemem i nie wiesz, którą drogę wybrać, opisz mi, skąd dziś biorą się Twoje faktury. Na stronie o automatyzacji faktur jest zakres prac, a bezpłatną rozmowę możesz umówić od razu.
Najczęstsze pytania
Czy da się wysłać fakturę do KSeF bez programowania?
Tak. Jeśli wystawiasz faktury w programie, który ma obsługę KSeF, program wysyła je za Ciebie. Jeśli chcesz wystawiać faktury z poziomu asystenta AI, serwer MCP do KSeF podłączasz raz w konfiguracji Claude Desktop albo Claude Code, a potem prosisz o fakturę zwykłym zdaniem.
Czym serwer MCP do KSeF różni się od integracji przez API?
Integrację z API piszesz sam: uwierzytelnianie, szyfrowanie, XML w formacie FA(3), sesje i statusy. Serwer MCP ma to już zrobione i wystawia gotowe narzędzia, z których korzysta model AI. Ty opisujesz, co ma się stać, a decyzję o wysyłce zatwierdzasz.
Gdzie bezpiecznie przetestować wysyłkę faktur do KSeF?
W środowisku TEST. Można tam używać fikcyjnych danych. W środowisku DEMO faktury też nie mają skutków prawnych. Dopiero na produkcji faktura ma moc prawną.
Skąd wziąć token KSeF?
Token generujesz w Aplikacji Podatnika KSeF po zalogowaniu Profilem Zaufanym, podpisem kwalifikowanym albo e-dowodem. Wybierasz uprawnienia, na przykład odczyt i wystawianie faktur, i kopiujesz token, bo wyświetla się tylko raz. Według README projektu generowanie tokenów w Aplikacji Podatnika jest dostępne do 31 grudnia 2026 r.
Czy AI może wysłać fakturę bez mojej zgody?
W ksef-mcp domyślny jest tryb ręcznego zatwierdzania. Faktura musi być zwalidowana, zablokowana i zatwierdzona, zanim pójdzie do KSeF, a zatwierdzenie wygasa po 15 minutach. Tryb automatyczny istnieje, ale README zaleca go tylko do testów.
Czy model AI widzi mój token KSeF?
Nie. Token i klucze zostają w środowisku serwera MCP i nie trafiają do modelu. NIP-y są maskowane w logach, a w logu audytowym zapisywany jest ich skrót.