ksef-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| KSEF_ENV | No | Srodowisko: test / demo / prod | test |
| KSEF_NIP | Yes | NIP podmiotu (10 cyfr) | |
| KSEF_TOKEN | Yes | Token autoryzacyjny KSeF | |
| KSEF_DATA_DIR | No | Katalog danych (drafty, sesja, audit) | ~/.ksef-mcp |
| KSEF_KEY_PATH | No | Sciezka do klucza prywatnego RSA | |
| KSEF_CERT_PATH | No | Sciezka do certyfikatu | |
| KSEF_LOG_LEVEL | No | Poziom logow: debug / info / warn / error | info |
| KSEF_APPROVAL_MODE | No | Tryb zatwierdzania: auto / manual | manual |
| KSEF_RATE_LIMIT_PER_HOUR | No | Limit zapytan na godzine | 1000 |
| KSEF_RATE_LIMIT_PER_MINUTE | No | Limit zapytan na minute | 200 |
| KSEF_RATE_LIMIT_PER_SECOND | No | Limit zapytan na sekunde | 5 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ksef_env_infoA | Pokaż aktualne środowisko KSeF, zamaskowany NIP i status sesji. Nie wymaga logowania. |
| ksef_env_setA | Zmień środowisko KSeF (test/demo/prod), NIP lub token w runtime. Pozwala przełączać się między produkcją a testami bez restartu. |
| ksef_auth_initA | Rozpocznij sesję KSeF używając tokena autoryzacyjnego (API v2). Flow: challenge → ksef-token → token/redeem → JWT access + refresh. NIP, token i środowisko można podać jako argumenty lub ustawić w env. |
| ksef_auth_statusA | Sprawdź status aktywnej sesji KSeF — czy jest aktywna, tokeny, ważność. |
| ksef_auth_terminateA | Zakończ aktywną sesję KSeF (unieważnij refresh token). Operacja nieodwracalna. |
| ksef_invoices_queryA | Wyszukaj faktury w KSeF po zakresie dat. Wymaga aktywnej sesji (ksef_auth_init). Zwraca metadane faktur: numer KSeF, NIP, kwota, data. |
| ksef_invoice_getA | Pobierz fakturę XML po numerze KSeF. Wymaga aktywnej sesji. Zwraca pełny XML faktury. |
| ksef_invoice_statusA | Sprawdź status przetwarzania faktury w sesji KSeF. Wymaga aktywnej sesji. Potrzebne: numer referencyjny sesji i numer referencyjny faktury. |
| ksef_invoice_xmlA | Pobierz XML faktury z KSeF po numerze KSeF (format FA(3)). Alias dla ksef_invoice_get. Wymaga aktywnej sesji. |
| ksef_upo_downloadA | Pobierz UPO (Urzędowe Poświadczenie Odbioru) dla faktury z sesji KSeF. UPO potwierdza przyjęcie faktury przez system. Wymaga aktywnej sesji. |
| ksef_draft_createA | Utwórz nowy draft faktury. Draft jest zapisywany lokalnie i może być edytowany przed walidacją i wysłaniem do KSeF. Oblicza automatycznie kwoty netto/VAT/brutto. |
| ksef_draft_getA | Pobierz draft faktury po ID. Zwraca pełne dane draftu z obliczonymi kwotami. |
| ksef_draft_listA | Wyświetl listę wszystkich draftów faktur. Opcjonalnie filtruj po statusie. |
| ksef_draft_updateA | Zaktualizuj draft faktury (patch). Można zmienić dowolne pola: dane sprzedawcy/nabywcy, numer, daty, pozycje. Przelicza kwoty automatycznie. Nie można edytować locked/sent. |
| ksef_draft_deleteA | Usuń draft faktury. Można usunąć tylko drafty w statusie draft lub error. |
| ksef_draft_validateA | Zwaliduj draft faktury wg reguł FA(3). Sprawdza: NIP (suma kontrolna), wymagane pola, poprawność dat, stawki VAT, spójność kwot. Jeśli walidacja przejdzie, status zmienia się na 'validated'. |
| ksef_draft_render_xmlA | Wygeneruj podgląd XML faktury w formacie FA(3) z draftu. Nie wysyła do KSeF — tylko renderuje XML. Draft powinien być wcześniej zwalidowany (ksef_draft_validate). |
| ksef_draft_lockA | Zablokuj draft do wysłania. Renderuje XML, oblicza hash SHA-256, ustawia status na 'locked'. Draft musi być wcześniej zwalidowany (ksef_draft_validate). Po zablokowaniu nie można go edytować. |
| ksef_approval_requestA | Utwórz żądanie zatwierdzenia (approval) dla zablokowanego draftu. Approval musi być potwierdzone przed wysłaniem faktury do KSeF. Wygasa po 15 minutach. Jeśli KSEF_APPROVAL_MODE=auto, zatwierdzenie jest automatyczne. |
| ksef_approval_confirmA | Potwierdź żądanie zatwierdzenia (approval). Weryfikuje, że approval jest aktywne, nie wygasło, i hash się zgadza. Po potwierdzeniu faktura jest gotowa do wysłania. |
| ksef_send_invoiceA | Wyślij zablokowaną i zatwierdzoną fakturę do KSeF. Wymaga: aktywnej sesji KSeF, draftu w statusie 'locked', potwierdzonego approval z pasującym hashem XML. Szyfruje XML (AES-256-CBC + RSA-OAEP) i wysyła do API KSeF. |
| ksef_audit_logA | Wyświetl ostatnie wpisy z logu audytowego. Log zawiera wszystkie operacje: tworzenie draftów, zatwierdzenia, wysyłki. NIP-y są zahashowane (SHA-256) dla bezpieczeństwa. |
| ksef_correction_createA | Utwórz korektę faktury na podstawie istniejącego draftu. Oryginalna faktura musi być wysłana do KSeF (mieć ksefReferenceNumber). Tworzy nowy draft z danymi oryginału, statusem 'draft' i powiązaniem z oryginałem. |
| ksef_correction_zeroA | Utwórz korektę zerującą na podstawie danych faktury z KSeF. Zeruje wszystkie pozycje (ilość → 0). Nie wymaga lokalnego draftu oryginału. |
| ksef_batch_openA | Otwórz sesję batch do wysyłania wielu faktur jednocześnie (API v2). Wymaga aktywnej sesji KSeF. Podaj rozmiar pliku, hash i listę części. Zwraca numer referencyjny i pre-signed URLs do uploadu części. |
| ksef_batch_send_partA | Wyślij część paczki na pre-signed URL uzyskany z ksef_batch_open. Wymaga aktywnej sesji KSeF i otwartej sesji batch. |
| ksef_batch_closeA | Zamknij sesję batch po wysłaniu wszystkich części. Wymaga aktywnej sesji KSeF. |
| ksef_batch_statusA | Sprawdź status sesji batch (lub online). Wymaga aktywnej sesji KSeF. |
| ksef_token_generateA | Wygeneruj nowy token KSeF. Wymaga aktywnej sesji KSeF. Zwraca numer referencyjny — NIE wartość tokena (nigdy nie eksponujemy sekretów). Token jest dostarczany przez KSeF osobnym kanałem. |
| ksef_token_listA | Wyświetl listę tokenów KSeF. Wymaga aktywnej sesji. Zwraca metadane — nigdy wartości tokenów. |
| ksef_token_getA | Pobierz szczegóły tokena KSeF. Wymaga aktywnej sesji. Zwraca metadane — nigdy wartość tokena. |
| ksef_token_revokeA | Unieważnij token KSeF. OPERACJA NIEODWRACALNA. Wymaga aktywnej sesji i potwierdzonego approval. Token po unieważnieniu nie może być przywrócony. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 32 tools
Most tools are clearly separated by resource and action, but ksef_invoice_xml is an explicit alias for ksef_invoice_get, creating a duplicate path to the same operation. Additionally, ksef_env_set and ksef_auth_init both accept NIP/token/environment, and ksef_batch_status overlaps somewhat with session status checks.
The dominant pattern is ksef_<resource>_<action>, which is used consistently across drafts, tokens, batches, and auth. Minor deviations include ksef_send_invoice reversing the order, ksef_invoices_query using a plural while ksef_invoice_get uses singular, and ksef_audit_log being a noun phrase rather than an action.
With 32 tools, the surface is heavy and exceeds the 25-tool threshold where a toolkit becomes difficult to navigate. The draft lifecycle alone accounts for 8 tools, and invoice retrieval has 4 tools including a redundant alias, making the count feel inflated even though each cluster is individually relevant.
The server covers the full KSeF invoice lifecycle well: draft creation through validation, locking, approval, sending, retrieval, corrections, batch sending, token management, and auditing. Minor gaps exist, such as no explicit approval rejection/cancellation tool and limited invoice search filters, but they are workable within the existing flow.