Dokument

Lokalny serwer MCP

Ostatnia aktualizacja: 2026-09-09

KSeF Katalog Pro może uruchomić lokalny serwer Model Context Protocol (MCP) na Twoim Macu. Daje to klientom MCP, takim jak Claude Code, Claude Desktop i Cursor, dostęp do faktur przez lokalny adres aplikacji.

Funkcja jest dostępna wyłącznie na macOS (sandbox iPadOS nie pozwala na nasłuchiwanie portów sieciowych) i wymaga aktywnego dostępu Pro (zakup jednorazowy lub subskrypcja miesięczna).

Co to jest MCP?

Model Context Protocol to otwarty standard opracowany przez Anthropic, który pozwala asystentom AI łączyć się z lokalnymi źródłami danych poprzez ujednolicony interfejs. Zamiast kopiować faktury do okna czatu, włączasz serwer w aplikacji i AI samo pobiera dokładnie te dane, których potrzebuje — np. „pokaż mi top 10 kontrahentów Q1” albo „przypisz wszystkie faktury z marca do katalogu Q1 2026”.

Połączenie między klientem MCP a KSeF Katalog odbywa się lokalnie na 127.0.0.1 — serwer nie jest dostępny z sieci LAN ani z internetu. Klient AI może jednak przekazać pobrany kontekst do swojego dostawcy modelu, aby wygenerować odpowiedź. Sprawdź politykę prywatności używanego klienta.

Wymagania

macOS 15.0 lub nowszy
Aktywny dostęp KSeF Katalog Pro (zakup jednorazowy lub subskrypcja miesięczna)
Klient MCP: Claude Code, Claude Desktop, Cursor lub mcp-inspector
Aplikacja KSeF Katalog uruchomiona (serwer zatrzymuje się przy zamknięciu aplikacji)
Node.js 18 lub nowszy, jeżeli łączysz się przez Claude Desktop

Tryby pracy

W Ustawieniach → MCP wybierasz jeden z trzech trybów:

Tryb	Co AI może	Use case
Off	Nic. Serwer wyłączony.	Domyślne ustawienie. Włączasz tylko gdy potrzebujesz.
Tylko odczyt	Listować, wyszukiwać, czytać faktury i statystyki	„Claude, ile mam faktur z marca?” / „Pokaż top 10 kontrahentów Q1”
Odczyt + zapis	Dodatkowo: przypisywać katalogi, tagi, kategorie pozycji; tworzyć nowe tagi/katalogi/kategorie	„Claude, oznacz wszystkie faktury z katalogu Q1 jako rozliczone” / „Przypisz pozycje z usługami SaaS do kategorii Software”

W trybie Odczyt + Zapis AI nigdy nie modyfikuje samej faktury — kwoty, daty, kontrahenci i pozycje są niemodyfikowalne, ponieważ KSeF jest jedynym autoryzowanym źródłem prawdy. Zmieniane są wyłącznie atrybuty wzbogacające, które dodajesz w aplikacji.

Każda zmiana wprowadzona przez AI trafia do Historii zmian (Ustawienia → Historia zmian) z możliwością cofnięcia pojedynczej operacji lub całej serii.

Włączanie serwera w aplikacji

Otwórz KSeF Katalog na Macu
Przejdź do Ustawienia (Cmd + ,)
Wybierz zakładkę MCP
Wybierz tryb: Tylko odczyt lub Odczyt + zapis
(Opcjonalnie) zmień port — domyślny to 3338

Serwer działa w trybie Streamable HTTP. Endpoint MCP to http://127.0.0.1:3338/mcp. Aplikacja nie wymaga autoryzacji — serwer nasłuchuje wyłącznie na interfejsie loopback (127.0.0.1), więc dostęp ograniczony jest do procesów uruchomionych na Twoim Macu.

Gdy serwer jest włączony, może się z nim połączyć każdy proces na tym Macu. Włączaj MCP tylko wtedy, gdy go używasz, i zaczynaj od trybu Tylko odczyt.

Konfiguracja klienta

Aplikacja KSeF Katalog ma wbudowaną pomoc — w Ustawienia → MCP → Skopiuj konfigurację znajdziesz gotowe snippety dla każdego klienta z aktualnym portem. Poniżej referencyjny opis każdego z czterech wspieranych klientów.

Claude Code (CLI)

Najprostszy sposób — jedna komenda w terminalu:

claude mcp add --transport http ksef-katalog http://127.0.0.1:3338/mcp

Claude Code zarejestruje serwer w konfiguracji globalnej i użyje go w każdej sesji. Wymaga zainstalowanego CLI claude.

Sanity check: w nowej sesji Claude Code napisz „wylistuj dostępne MCP servery”. KSeF Katalog powinien być widoczny z dostępnymi narzędziami (list_invoices, get_invoice, search_invoices, …).

Claude Desktop

Claude Desktop nie przyjmuje lokalnego adresu Streamable HTTP bezpośrednio w claude_desktop_config.json. Plik konfiguracyjny uruchamia serwery przez stdio, dlatego połączenie z działającą aplikacją wymaga mostka mcp-remote.

Sprawdź w Terminalu, czy masz Node.js 18 lub nowszy: node --version
W KSeF Katalog skopiuj aktywny adres z Ustawienia → MCP. Domyślnie jest to http://127.0.0.1:3338, ale aplikacja może użyć innego portu, jeżeli wybrany jest zajęty.
Otwórz plik ~/Library/Application Support/Claude/claude_desktop_config.json (jeżeli nie istnieje — utwórz).
Dodaj konfigurację, używając aktywnego adresu:

{
  "mcpServers": {
    "ksef-katalog": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3338/mcp"]
    }
  }
}

Zamknij Claude Desktop przez Cmd + Q i uruchom go ponownie.

Przy pierwszym uruchomieniu npx pobierze niezależny pakiet open source mcp-remote. KSeF Katalog go nie instaluje ani nie aktualizuje.

Sprawdzenie: w oknie czatu Claude Desktop kliknij + → Connectors. Powinieneś zobaczyć ksef-katalog z listą dostępnych narzędzi. Stan połączenia i logi znajdziesz również w ustawieniach deweloperskich Claude Desktop.

Opcja Add custom connector nie zadziała z tym adresem. Zdalne Connectors łączą się z infrastruktury Anthropic i wymagają serwera dostępnego publicznie przez HTTPS; nie mają dostępu do 127.0.0.1 na Twoim Macu.

Cursor

Otwórz Cursor Settings → MCP (lub edytuj ~/.cursor/mcp.json)
Wklej:

{
  "mcpServers": {
    "ksef-katalog": {
      "url": "http://127.0.0.1:3338/mcp"
    }
  }
}

Zrestartuj Cursor

Sanity check: w panelu Cursor MCP serwer ksef-katalog powinien mieć status Connected (zielona kropka).

mcp-inspector

Narzędzie debugujące — najlepsze do pierwszego sprawdzenia, że serwer w ogóle odpowiada:

npx @modelcontextprotocol/inspector

W oknie inspektora wybierz Streamable HTTP i wklej URL http://127.0.0.1:3338/mcp. Po połączeniu zobaczysz listę narzędzi i będziesz mógł je wywołać ręcznie.

Czego AI nie może?

To, czego serwer nigdy nie zrobi — niezależnie od trybu i pomysłowości promptu:

Nie zmieni faktury. Kwoty, daty, kontrahenci, pozycje, numer KSeF — wszystko jest niemodyfikowalne. KSeF to autorytatywne źródło, aplikacja nigdy nie nadpisze danych z XML.
Nie wystawi serwera poza Twój Mac. KSeF Katalog nasłuchuje wyłącznie na 127.0.0.1, bez routingu z LAN ani z internetu. Osobny klient AI może jednak przesłać pobrane dane do swojego dostawcy modelu.
Nie zobaczy Twojego klucza KSeF. Token autoryzacyjny KSeF i NIP są w Keychain — nie są wystawiane jako narzędzia MCP. AI ma dostęp wyłącznie do faktur, które już zostały pobrane do bazy.
Nie będzie działać w tle. Serwer zatrzymuje się natychmiast przy zamknięciu aplikacji (App Sandbox nie pozwala na background daemon). Żeby AI miało dostęp — aplikacja musi być uruchomiona.
Nie pominie audytu. Każda mutacja w trybie Odczyt + Zapis trafia do Historii zmian z oznaczeniem źródła mcp i znacznikiem czasu. Możesz cofnąć każdą zmianę pojedynczo albo grupowo.

FAQ

Czy mogę używać MCP na iPadzie albo iPhonie?

Nie. Funkcja jest dostępna wyłącznie na macOS. Sandbox iPadOS i iOS nie pozwala aplikacjom nasłuchiwać na portach sieciowych — to ograniczenie systemowe, nie projektowe.

Czy mogę używać Claude Desktop natywnie bez `mcp-remote`?

Nie w przypadku lokalnego endpointu HTTP KSeF Katalog. claude_desktop_config.json uruchamia lokalne integracje przez stdio, a KSeF Katalog udostępnia Streamable HTTP. mcp-remote tłumaczy te dwa transporty. Alternatywą na przyszłość byłoby dostarczenie KSeF Katalog jako rozszerzenia Desktop Extension (.mcpb), które również komunikuje się z Claude Desktop przez stdio.

Czy AI widzi mój klucz KSeF API?

Nie. Token KSeF i NIP są przechowywane w systemowym Keychain i nie są wystawiane jako narzędzia MCP. Asystent AI ma dostęp wyłącznie do danych faktur, które już zostały pobrane do lokalnej bazy aplikacji.

Czy serwer działa w tle gdy zamknę aplikację?

Nie. Serwer zatrzymuje się natychmiast przy zamknięciu aplikacji. Wynika to z polityki App Sandbox macOS — aplikacje z App Store nie mogą uruchamiać background daemonów. To świadoma decyzja: chcesz mieć kontrolę nad tym, kiedy serwer jest aktywny.

Czy mogę uruchomić więcej niż jednego klienta jednocześnie?

Tak. Możesz mieć równolegle podpięty Claude Code i Cursor — serwer obsługuje wiele połączeń HTTP. Pamiętaj jednak o rate limitach: 100 odczytów / minutę i 30 zapisów / minutę. Limity są wspólne dla wszystkich klientów.

Czy mogę zmienić port serwera?

Tak. W Ustawienia → MCP → Port wybierasz dowolny port wyższy niż 1024 (domyślnie 3338). Jeżeli wybrany port jest zajęty, aplikacja zaalokuje losowy port wyższy niż 49152. Pamiętaj o zaktualizowaniu URL w konfiguracji klienta po zmianie.

Co z bezpieczeństwem przy publicznym Wi-Fi?

Serwer nasłuchuje tylko na interfejsie loopback (127.0.0.1), więc nawet w niezabezpieczonej sieci publicznej Twoje faktury nie są dostępne dla innych urządzeń. Loopback jest izolowany od interfejsów sieciowych — bez wyjątku.

Gdzie znajdę audyt wywołań MCP?

W Ustawieniach → MCP → Dziennik wywołań widzisz ostatnie 100 wywołań (timestamp, tool, status). Mutacje znajdziesz dodatkowo w Ustawieniach → Historia zmian z możliwością cofnięcia.

Prywatność

KSeF Katalog nie wysyła danych z serwera MCP do własnej chmury. Po podłączeniu klienta AI sposób przetwarzania danych zależy również od tego klienta i jego dostawcy modelu. Pełen opis znajduje się w Polityce prywatności § 4a.

Pomoc

Masz pytanie albo problem z konfiguracją? Napisz:

E-mail: contact@thehardway.pl
Wsparcie: /wsparcie