Użycie z AI (MCP)

Ksefnik działa jako serwer MCP (Model Context Protocol) — otwartego standardu komunikacji między asystentami AI a zewnętrznymi narzędziami. Dzięki temu możesz rozmawiać z AI o swoich fakturach KSeF i przelewach bankowych w języku naturalnym.

Co to jest MCP?

Model Context Protocol to otwarty standard stworzony przez Anthropic. Definiuje sposób, w jaki asystent AI (np. Claude, Cursor) może wywoływać narzędzia zewnętrzne — pobierać dane, uruchamiać analizy, wykonywać akcje.

Ksefnik udostępnia 9 narzędzi MCP. Asystent AI sam decyduje, kiedy i które narzędzie wywołać, na podstawie Twojego pytania.

Instalacja

Zero instalacji. Wystarczy npx:

npx @ksefnik/mcp

Klient AI (Claude Desktop, Cursor, Claude Code) uruchomi serwer automatycznie przy pierwszym użyciu.

Konfiguracja

Edytuj plik ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) lub %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi...",
        "KSEF_ENV": "demo"
      }
    }
  }
}

Po zapisaniu pliku zrestartuj Claude Desktop. Ksefnik pojawi się na liście dostępnych narzędzi.

Utwórz plik .cursor/mcp.json w katalogu projektu:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi...",
        "KSEF_ENV": "demo"
      }
    }
  }
}

claude mcp add ksefnik -- npx -y @ksefnik/mcp

Lub dodaj do .claude/settings.json:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi...",
        "KSEF_ENV": "demo"
      }
    }
  }
}

Zmienne środowiskowe

Zmienna	Wymagana	Opis
`KSEF_NIP`	Tak	NIP podmiotu (10 cyfr)
`KSEF_TOKEN`	Nie	Token autoryzacyjny KSeF
`KSEF_ENV`	Nie	Środowisko: `prod`, `demo` lub `test` (domyślnie `demo`)

Serwer akceptuje również aliasy: KSEFNIK_NIP, KSEFNIK_TOKEN, KSEFNIK_ENV.

Dostępne narzędzia

Ksefnik udostępnia 9 narzędzi MCP:

Narzędzie	Opis
`sync-invoices`	Synchronizacja faktur z KSeF
`query-invoices`	Wyszukiwanie faktur
`import-bank`	Import wyciągu bankowego
`reconcile`	Uzgadnianie faktur z przelewami
`get-unmatched`	Nieuzgodnione pozycje z raportu
`send-invoice`	Wysyłka faktury do KSeF
`validate-invoice`	Walidacja faktury
`confirm-match`	Potwierdzenie dopasowania
`get-upo`	Sprawdzenie statusu UPO (potwierdzenie odbioru)

Szczegółowa dokumentacja każdego narzędzia: Konfiguracja serwera MCP.

Przykładowa rozmowa

Poniżej typowy scenariusz — księgowa sprawdza uzgodnienie za marzec:

Otwierasz Claude Desktop z podłączonym serwerem ksefnik.
Piszesz: “Pobierz faktury za marzec 2026 i zaimportuj wyciąg z pliku ~/Documents/wyciag-marzec.csv”.
Claude wywołuje sync-invoices z datami marca, potem import-bank z podaną ścieżką.
Piszesz: “Uruchom uzgadnianie i pokaż co nie pasuje”.
Claude wywołuje reconcile, potem get-unmatched i odpowiada:

“Uzgodniłem 12 z 15 faktur (match rate 80%, średnia pewność 93%). 3 faktury bez przelewu:
- FV/2026/03/012 — 4 500 PLN (ACME sp. z o.o.)
- FV/2026/03/018 — 1 230 PLN (TechSoft)
- FV/2026/03/021 — 8 900 PLN (DataCorp)”
Piszesz: “Sprawdź UPO dla faktury KSeF-1234567890-20260310-ABC123”.
Claude wywołuje get-upo i potwierdza status odbioru.

Przykładowe prompty

Podstawowe operacje

“Pobierz faktury za marzec 2026 i pokaż podsumowanie”
“Zaimportuj wyciąg bankowy z pliku wyciag-marzec.csv”
“Uruchom uzgadnianie za marzec z wyciągiem z mBanku”

Analiza danych

“Które faktury z marca nie mają przelewu?”
“Jaka jest łączna kwota niesparowanych faktur?”
“Pokaż faktury od kontrahenta z NIP 7740001454”
“Jaki jest match rate za marzec?”

Zaawansowane pytania

“Porównaj match rate z lutego i marca — czy się poprawił?”
“Znajdź faktury powyżej 10 000 PLN, które nie zostały opłacone”
“Zwaliduj fakturę FV/2026/03/042 przed wysyłką do KSeF”
“Sprawdź UPO dla ostatnio wysłanej faktury”