Dla programistów: serwer MCP

Serwer MCP pozwala Twojemu programowi AI (np. Claude Desktop) wywoływać funkcje SprawdźKSeF na plikach z Twojego komputera: otworzyć fakturę, sprawdzić jej zgodność ze schematem, porównać PDF z XML, znaleźć duplikaty, pobrać dane do przelewu. Serwer działa lokalnie i po pobraniu pakietu nie łączy się z siecią.

Zaktualizowano 28 października 2026 · informacja ogólna, nie porada podatkowa

1. Co to jest MCP

MCP (Model Context Protocol) to otwarty protokół, którym programy AI wywołują narzędzia dostarczane przez lokalne lub zdalne serwery. W tym wariancie serwer jest uruchamiany na Twoim komputerze i komunikuje się z klientem przez standardowe wejście i wyjście (stdio).¹ Faktury czyta lokalny proces, a nie nasz serwer; nie mamy zresztą żadnego serwera, który je przetwarza.

Model AI Twojego klienta zobaczy wyniki wywołań narzędzi, więc dane z nich trafiają do niego na warunkach dostawcy tego klienta. Jeśli nie chcesz, żeby treść faktur opuszczała komputer, użyj klienta z modelem lokalnym albo klienta bez modelu (patrz punkt 8).

2. Wymagania

• Node.js w wersji 22 lub nowszej. Do uruchomienia MCP Inspectora (punkt 8) potrzebujesz Node 22.19 lub nowszego.
• Klient MCP, który obsługuje serwery stdio (np. Claude Desktop).¹
• Brak konta i klucza API od nas. Serwer jest darmowy, a koszt modelu AI zależy od klienta, którego używasz.

3. Uruchomienie

npx -y sprawdzksef-mcp@0.0.1 --allow /ścieżka/do/katalogu/z/fakturami

Zawsze podawaj dokładną wersję (na przykład @0.0.1, a nie @latest). Dzięki temu aktualizacja następuje wtedy, gdy ją wybierzesz. Aby zaktualizować, zmień numer wersji w poleceniu lub konfiguracji klienta. Pakiet ma być publikowany z poświadczeniem pochodzenia (npm provenance).

4. Konfiguracja klienta

Przykład dla Claude Desktop. Plik konfiguracyjny to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) albo %APPDATA%\Claude\claude_desktop_config.json (Windows); do otwarcia go służy w ustawieniach zakładka „Developer” i przycisk „Edit Config”.¹ Po zmianie trzeba całkowicie zamknąć i uruchomić klienta ponownie.¹

{
  "mcpServers": {
    "sprawdzksef": {
      "command": "npx",
      "args": ["-y", "sprawdzksef-mcp@0.0.1", "--allow", "/Users/anna/Faktury"]
    }
  }
}

Ścieżki w args muszą być bezwzględne.¹ Wersję zamień na aktualną po wydaniu. Inne klienty z polem mcpServers używają podobnego formatu, ale sprawdź ich dokumentację.

5. Dostęp do plików

• --allow <katalog>: serwer może czytać pliki z tego katalogu. Możesz podać kilka.
• --allow-write <katalog>: serwer może zapisywać nowe pliki (PDF, CSV) tylko w tym katalogu, domyślnie wyłączone. Istniejących plików nie nadpisuje.
• Serwer rozwiązuje ścieżki do rzeczywistych i odrzuca dowiązania symboliczne wychodzące z katalogu, fragmenty .. oraz ścieżki spoza dozwolonych katalogów.
• Limity rozmiaru: 10 MB dla XML, 200 MB dla ZIP, 50 MB dla PDF.
• Pakiet pobierzesz z rejestru npm przy pierwszym uruchomieniu (npx); później serwer działa bez sieci. Serwer nie wykonuje żądań sieciowych. Logi trafiają tylko na stderr i nie zawierają treści faktur.

6. Narzędzia

Wszystkie narzędzia poza render_pdf i export_table tylko czytają. Dwa wymienione zapisują plik i działają wyłącznie z opcją --allow-write.

Funkcje związane z oknem przeglądarki (np. otwarcie strony MF, druk, nawigacja, wpisanie numeru KSeF) nie są dostępne w MCP. Numer KSeF przekazujesz wtedy jako argument narzędzia.

Planowane później: porównanie dwóch faktur (compare_invoices), interfejs wiersza poleceń (CLI) i, za flagą, udostępnianie narzędzi agentowi w przeglądarce (WebMCP). Zdalny serwer MCP rozważamy tylko wtedy, gdy znajdzie się hosting w planie darmowym bez karty. Jeśli nie, narzędzia zostaną wyłącznie lokalne.

7. Bezpieczeństwo

• Treść faktury to dane niezaufane. Nazwy, opisy i adresy wpisuje wystawca faktury i może on umieścić tam tekst przypominający polecenie dla AI. W odpowiedziach oznaczamy takie pola znacznikiem untrusted: true. Skonfiguruj klienta tak, aby nie wykonywał poleceń z treści faktury, i zwracaj uwagę na prośby o dodatkowe działania.
• Najmniejsze uprawnienia. Udostępniaj tylko katalogi z fakturami. Zapis włączaj tylko wtedy, gdy go potrzebujesz.
• Numer rachunku do przelewu pochodzi wyłącznie z danych płatności faktury. Jeśli w treści jest inny numer konta, narzędzie get_payment_details zwróci ostrzeżenie. Zawsze potwierdź rachunek u sprzedawcy innym kanałem, zanim zrobisz przelew.
• Odpowiedzialność za działania agenta AI leży po stronie klienta, którego używasz.

8. Wypróbowanie bez modelu AI

Serwer możesz sprawdzić w MCP Inspector, oficjalnym darmowym narzędziu projektu MCP do testowania serwerów. Uruchamia się je przez npx i wymaga Node 22.19.0 lub nowszego.² Pozwala ono wywołać narzędzia ręcznie, bez modelu AI i bez konta:

npx @modelcontextprotocol/inspector npx -y sprawdzksef-mcp@0.0.1 --allow /ścieżka/do/faktur

9. Przykłady poleceń dla AI

Wynik zależy od modelu klienta; poniższe zdania są przykładami, nie gwarancją.

• „Sprawdź faktury z folderu Faktury i wskaż duplikaty.”
• „Czy PDF faktury X zgadza się z jej XML?”
• „Ile, na jakie konto i z jakim tytułem mam zapłacić za fakturę Y?”
• „Zapisz tabelę wszystkich faktur do CSV.” (wymaga --allow-write)

Licencja

Treść tej strony: licencja CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/deed.pl), autor: SprawdźKSeF (sprawdzksef.pl).