· Dokument

Lokalny serwer MCP

Ostatnia aktualizacja: 2026-05-10

KSeF Katalog Pro może uruchomić lokalny serwer Model Context Protocol (MCP) na Twoim Macu. Daje to asystentom AI (Claude Code, Claude Desktop, Cursor) bezpieczny, lokalny dostęp do Twoich faktur — bez wysyłania ich do chmury.

Funkcja jest dostępna wyłącznie na macOS (sandbox iPadOS nie pozwala na nasłuchiwanie portów sieciowych) i wymaga aktywnej subskrypcji Pro (lifetime lub 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”.

Cała komunikacja odbywa się lokalnie na 127.0.0.1 — serwer nie jest dostępny z sieci LAN ani z internetu. Żadne dane nie wychodzą poza Twój Mac.

Wymagania

macOS 15.0 lub nowszy
Aktywna subskrypcja KSeF Katalog Pro (lifetime lub miesięczna)
Klient MCP: Claude Code, Claude Desktop, Cursor lub mcp-inspector
Aplikacja KSeF Katalog uruchomiona (serwer zatrzymuje się przy zamknięciu aplikacji)

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.

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

Otwórz plik ~/Library/Application Support/Claude/claude_desktop_config.json (jeżeli nie istnieje — utwórz)
Wklej:

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

Zrestartuj Claude Desktop (Cmd + Q i ponownie uruchom)

Sanity check: w oknie czatu Claude Desktop kliknij ikonę MCP (dół-prawo). Powinieneś zobaczyć ksef-katalog z listą dostępnych narzędzi.

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 wyjdzie poza Twój Mac. Serwer nasłuchuje wyłącznie na 127.0.0.1, nie ma routingu z LAN ani z internetu. Bez sieciowego nasłuchu na 0.0.0.0.
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`?

Tak — od czasu wprowadzenia Streamable HTTP transport Claude Desktop podłącza się natywnie do http://127.0.0.1:<port>/mcp. mcp-remote jako proxy nie jest już wymagany. Konfiguracja powyżej ("type": "http") używa transportu natywnego.

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ść

Lokalny serwer MCP nie zmienia modelu prywatności aplikacji — wszystkie dane pozostają lokalnie na Twoim Macu. Pełen opis w Polityce prywatności § 4a.

Pomoc

Masz pytanie albo problem z konfiguracją? Napisz:

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