MCP — integracja z asystentami AI#

KSeFka obsługuje protokół MCP (Model Context Protocol) — standard pozwalający asystentom AI (Claude, Cursor i innym) bezpośrednio tworzyć faktury, zarządzać kontrahentami i pobierać dane bez opuszczania czatu.

Wymagania#

Zainstalowana aplikacja KSeFka
Skonfigurowana firma (Ustawienia → Firmy)
Wybrane środowisko KSeF (test / demo / produkcja)

Uruchomienie serwera#

Serwer MCP uruchamia się przez CLI jako proces stdio — klient AI zarządza jego cyklem życia automatycznie:

ksefka mcp

✦

Szybsza konfiguracja: Wklej do czatu z AI: https://ksefka.com/llms.txt — asystent sam się skonfiguruje i wyjaśni jak zacząć.

Konfiguracja Claude Desktop#

Otwórz plik konfiguracyjny Claude Desktop (claude_desktop_config.json) i dodaj wpis:

{
  "mcpServers": {
    "ksefka": {
      "command": "ksefka",
      "args": ["mcp"]
    }
  }
}

Lokalizacja pliku konfiguracyjnego:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Konfiguracja Cursor#

W ustawieniach Cursor przejdź do MCP Servers i dodaj:

{
  "ksefka": {
    "command": "ksefka",
    "args": ["mcp"]
  }
}

Dostępne narzędzia#

Narzędzie	Opis
Faktury
`list_invoices`	Lista faktur z filtrowaniem po kierunku, miesiącu, statusie, kontrahencie i wartości
`get_invoice`	Szczegóły faktury wraz z pozycjami
`create_invoice`	Utwórz fakturę (VAT, korygującą, zaliczkową, rozliczeniową) — dane jako obiekt JSON
`finalize_invoice`	Przenieś szkic do stanu „gotowa do wysłania do KSeF"
`unfinalize_invoice`	Cofnij finalizację faktury z powrotem do szkicu
`copy_invoice`	Skopiuj fakturę jako nowy szkic z dzisiejszą datą
`open_invoice`	Otwórz fakturę w aplikacji desktopowej do podglądu lub edycji
Kontrahenci
`list_contractors`	Lista kontrahentów z wyszukiwaniem po nazwie lub NIP
`get_contractor`	Pełne dane kontrahenta
`create_contractor`	Dodaj nowego kontrahenta
`update_contractor`	Zaktualizuj dane kontrahenta
`delete_contractor`	Usuń (dezaktywuj) kontrahenta
`lookup_company_by_nip`	Pobierz dane firmy z rejestru GUS BIR1 na podstawie NIP
Produkty
`list_products`	Lista produktów/usług z katalogu
`get_product`	Szczegóły produktu
`create_product`	Dodaj produkt do katalogu
Raporty i kursy walut
`monthly_summary`	Podsumowanie miesięczne: suma przychodów i kosztów
`dashboard_stats`	Statystyki bieżącego miesiąca
`fetch_nbp_rate`	Kurs średni NBP dla waluty na dany dzień
Szablony i KSeF
`list_templates`	Lista szablonów faktur
`ksef_authorize`	Zapisz token autoryzacyjny KSeF

Przykład#

Wpisujesz do czatu:

„Stwórz fakturę dla Acme Sp. z o.o. za 10 godzin programowania po 200 zł netto, VAT 23%, termin płatności 14 dni."

AI kolejno wywołuje:

list_contractors — szuka „Acme" w bazie kontrahentów
create_invoice — tworzy fakturę: kierunek issued, 1 pozycja (10 h × 200 zł, VAT 23%), kontrahent z poprzedniego kroku, termin płatności +14 dni
open_invoice — otwiera fakturę w aplikacji do podglądu i ewentualnej korekty

Efekt: w KSeFce pojawia się gotowy szkic faktury na kwotę 2460 zł brutto (2000 zł netto + 460 zł VAT). Możesz go przejrzeć, poprawić i wysłać do KSeF — bez ręcznego wypełniania formularza.

Serwer MCP zawiera wbudowane instrukcje dla AI dotyczące faktur korygujących, zaliczkowych, rozliczeniowych oraz faktur w walutach obcych z automatycznym kursem NBP.

Dokumentacja