Claude, MCP i KSeF — jak pytać AI o faktury lokalnie

TL;DR. Model Context Protocol (MCP) to otwarty protokół pozwalający asystentom AI (Claude, inne LLM-y) odpytywać dane z lokalnych narzędzi przez standardowy interfejs tool-calli. Dla firmy z bazą faktur KSeF oznacza to konkretnie: możesz zapytać Claude Desktop "ile wydaliśmy na IT w Q1?" i model sięgnie do twojej lokalnej bazy zamiast halucynować. Kluczowa właściwość — pełne dane nie opuszczają infrastruktury, do chmury modelu idą tylko odpowiedzi na konkretne zapytania. Ten artykuł tłumaczy, jak MCP działa, jakie ma ograniczenia i jak go złożyć w stos z KSeF.

Czym jest MCP w dwie minuty

Model Context Protocol to specyfikacja opublikowana przez Anthropic pod koniec 2024 roku jako open-source, a w 2025 przyjęta szerzej w ekosystemie AI (oficjalna strona: modelcontextprotocol.io; dokumentacja integracji z Claude: docs.anthropic.com — sprawdź aktualną sekcję "Build with Claude / MCP"). Idea jest bliska temu, czym USB-C jest dla urządzeń elektronicznych: standardowy port, który pozwala różnym klientom (Claude Desktop, Claude Code, Cursor, VS Code, aplikacje firm trzecich) rozmawiać z różnymi źródłami danych (baza, filesystem, API wewnętrzne) bez pisania każdej integracji od zera.

Mechanika jest prosta:

• MCP server — mały proces uruchomiony lokalnie na komputerze użytkownika (lub w sieci firmowej). Wystawia listę tool-calli, czyli funkcji, które model może wywołać: get_invoices(month), get_cost_by_department(q), search_invoices(query).
• MCP client — aplikacja AI, w której rozmawiasz z modelem (najczęściej Claude Desktop). Klient wie, że dany server istnieje, zna listę jego narzędzi i pokazuje ją modelowi.
• Model — Claude albo inny LLM — otrzymuje twoje pytanie w języku naturalnym, decyduje, czy potrzebuje uruchomić któreś z narzędzi, wysyła zapytanie przez klienta do serwera, odbiera wynik i formatuje odpowiedź.

Ważne: model nie widzi bezpośrednio danych z twojej bazy. Widzi tylko wyniki tych konkretnych tool-calli, które sam wykonał. Jeśli zapytasz "pokaż faktury od Tauronu w marcu", model dostanie listę 40 faktur — nie całej bazy. Cały pipeline działa na twoim komputerze; do serwerów Anthropic idą tylko: twoje pytanie, wyniki tool-calli, odpowiedź modelu.

Dlaczego to ma znaczenie dla firm w Polsce

KSeF generuje gigantyczną ilość strukturalnych danych. Każda faktura FA(3) to dokument z kilkudziesięcioma ustandaryzowanymi polami: kontrahent, NIP, kwoty netto/VAT, pozycje, daty, stawki VAT. Dla modelu AI to idealny kontekst — lepszy niż PDF, lepszy niż skany, lepszy niż rozproszone maile. Problem polega na czymś innym: dane z KSeF są bardzo wrażliwe. Kto z kim handluje, za ile, co kupuje, jakie marże, struktury kosztowe — to informacje, których nie chcesz wysyłać do chmury żadnego vendora AI.

MCP rozwiązuje ten kompromis. Pytasz Claude pytanie naturalne — "pokaż faktury od kontrahenta X z Q2 i zsumuj koszty po kategoriach". Pod spodem:

1. Claude tłumaczy pytanie na jeden lub kilka tool-calli (np. search_invoices(contractor="X", quarter="Q2 2026"), potem aggregate_by_category()).
2. Twój lokalny MCP server wykonuje zapytania SQL (lub inne) na lokalnej bazie faktur.
3. Server zwraca wynik — przykładowo 87 faktur, zsumowane kwoty w 6 kategoriach.
4. Claude formatuje wynik po polsku, dodaje komentarz analityczny, sugeruje kolejne pytania.

Jest to inna architektura niż ChatGPT z Advanced Data Analyst (dawniej Code Interpreter), gdzie wrzucasz plik CSV do chmury OpenAI i tam model go analizuje. W modelu MCP plik nie opuszcza twojego dysku. Do modelu idą tylko odpowiedzi na pytania, które sam zadał. Szczegółowy rozkład ryzyk prywatności opisuje artykuł KSeF a bezpieczeństwo danych.

Scenariusze użycia z Claude Desktop + KSeF

Poniżej przykłady pytań, które można realnie zadać Claude Desktop, gdy MCP server ma dostęp do lokalnej bazy z fakturami z KSeF. Dla każdego scenariusza krótka nota: jakie tool-calle muszą być wystawione i jakie zabezpieczenia są sensowne.

"Ile wydaliśmy miesiąc do miesiąca na paliwo w Q1 2026?"

Tool-call: get_invoices_by_category(category="paliwo", date_from, date_to), ew. aggregate_monthly(sum_net). Zabezpieczenie: read-only, bez pisania. Kategoria "paliwo" musi być wcześniej ustalona (słownik kontrahentów lub reguły na opisach pozycji) — model jej sam nie wymyśli.

"Który kontrahent przekroczył budżet w kategorii Marketing?"

Tool-calle: get_budget(category="marketing", period) + get_invoices_by_category("marketing", period) + compare_to_budget(). Zabezpieczenie: server musi mieć dostęp do budżetu (plan) i do realizacji (KSeF). Budżetu w KSeF nie ma — to dane wewnętrzne firmy, trzymane najczęściej w Excelu, Jedoxie, Anaplanie (por. KSeF dla controllingu).

"Znajdź faktury wystawione przed 1.04.2026 ale otrzymane po — czy są zgodne z okresem rozliczenia?"

Tool-call: search_invoices(issue_date_before, receipt_date_after). Zabezpieczenie: read-only. Odpowiedź dotyczy split-periodu i rozliczenia VAT — model nie powinien formułować wiążącej interpretacji podatkowej, zostaw to księgowej.

"Porównaj koszty oddziału Warszawa i Kraków w marcu 2026"

Tool-calle: get_costs_by_branch(branch, month) dla dwóch oddziałów, potem compare(). Zabezpieczenie: klasyfikacja po oddziałach musi być wcześniej wykonana (faktury przypisane do MPK lub kodu oddziału). Bez tej warstwy model zwróci rekordy nieposortowane. Więcej: klasyfikacja faktur po oddziałach.

"Wygeneruj draft sprawozdania DG-1 za kwiecień — wypełnij pola, których dane mamy"

Tool-calle: get_sales_summary(period), get_employment_count(period), fill_dg1_template(data). Zabezpieczenie: model tworzy draft, nie wysyła formularza. Finalne zatwierdzenie po stronie człowieka. Sprawozdanie DG-1 opisane szerzej w osobnym artykule.

Czego MCP nie robi — ograniczenia

MCP to transport i standard — nie jest magią. Warto znać granice.

• MCP to nie AI. MCP nie rozumie pytań, nie rozumie danych, nie klasyfikuje niczego. Cała inteligencja jest w modelu (Claude, inny LLM). MCP to tylko standardowy sposób wywołania funkcji z kodu modelu.
• Claude wciąż może halucynować. Dane wejściowe są prawdziwe (bo pochodzą z twojej bazy), ale model może źle zinterpretować wynik, błędnie zaokrąglić, pomylić miesiąc z kwartałem, nadinterpretować trend. Wrażliwe wnioski (szczególnie podatkowe) zawsze weryfikuj z osobą kompetentną.
• Tool-calle muszą być zdefiniowane z góry. Model nie odkryje nowego zapytania, które nie zostało zaimplementowane. Jeśli potrzebujesz pytań typu "pokaż niezafakturowane zamówienia", musisz dodać odpowiedni tool-call do MCP server'a.
• Wymaga lokalnej instalacji. Claude Desktop + MCP server = dodatkowe oprogramowanie na komputerze. IT działu firmy musi to włączyć do listy dozwolonych aplikacji.
• Nie zastępuje ERP ani FK. MCP to warstwa zapytań analitycznych nad bazą tylko-do-odczytu. Transakcje (księgowanie, płatności, obrót magazynowy) nadal robisz w systemie ERP i w programach księgowych.
• Ryzyko zapisu. Jeśli MCP server wystawia tool-calle modyfikujące dane (np. update_invoice_status()), model potencjalnie może zmienić coś, czego nie chciałeś. Rekomendacja: zaczynaj od server'a read-only. Tool-calle zmieniające stan — osobny, późniejszy etap, z potwierdzaniem akcji przez użytkownika.
• Audytowalność wymaga implementacji. Loguj każdy tool-call ze znacznikiem czasu, argumentami i kontem klienta. Inaczej nie wiesz, kto i kiedy pytał o co.

Architektura: jak poskładać Claude + KSeF + firma

Typowy stos ma cztery warstwy, złożone pionowo od źródła danych do interfejsu użytkownika:

• Warstwa 1 — KSeF. Źródło prawdy dla faktur. Dostęp przez API Ministerstwa Finansów, dokumentacja na ksef.podatki.gov.pl. Narzędzie do pobierania (Pianista lub inne) łączy się z KSeF, ściąga faktury FA(3) i zapisuje je lokalnie.
• Warstwa 2 — lokalna baza danych. SQLite (dla małych instalacji) albo PostgreSQL (dla firm średnich i większych). Zawiera wszystkie faktury kosztowe i sprzedażowe w ustrukturyzowanej formie. Dodatkowo: słowniki kategorii, oddziałów, MPK, projektów. Ta baza nie musi być dostępna z internetu — wystarczy sieć lokalna firmy.
• Warstwa 3 — MCP server. Proces w Pythonie lub TypeScripcie (oficjalne SDK Anthropic), który wystawia tool-calle read-only nad bazą. Typowo: search_invoices, get_totals_by_category, get_cost_by_branch, get_budget_variance. Każdy tool-call ma zdefiniowaną sygnaturę i sanityzację argumentów (zwłaszcza jeśli wyciągasz do SQL).
• Warstwa 4 — Claude Desktop. Skonfigurowany tak, żeby widział twój MCP server. Użytkownik (controller, CFO, księgowa) rozmawia naturalnie z Claude, a model w tle wykonuje tool-calle do server'a.

Na żadnym z tych etapów pełne dane kontrahentów, kwoty i marże nie opuszczają infrastruktury firmy. Do Anthropic idą tylko: tekst twojego pytania, wyniki konkretnych tool-calli (które Claude poprosił), finalna odpowiedź. Jeśli chcesz jeszcze dalej ograniczyć to, co widzi chmura — anonimizuj pola kontrahentów po stronie MCP server'a przed wysłaniem wyniku do modelu.

Pianista a MCP

Pianista to desktopowa aplikacja do obsługi faktur KSeF — pobiera dokumenty z API KSeF, klasyfikuje je po oddziałach, kategoriach i MPK, i zapisuje do lokalnej bazy SQLite lub PostgreSQL postawionej w infrastrukturze firmy. Dane nie opuszczają komputera użytkownika ani serwerów firmowych.

W kontekście MCP oznacza to konkretnie: Pianista dostarcza fundament danych w formacie, który łatwo opakować we własny MCP server. Jeśli uruchomisz nad bazą Pianisty własny proces MCP (np. w Pythonie, kilkadziesiąt linii kodu z oficjalnym SDK Anthropic), zyskujesz możliwość pytania Claude o faktury bez przesyłania ich do chmury. Stos działa w pełni lokalnie, dane zostają u ciebie.

Ważne zastrzeżenie: na kwiecień 2026 Pianista nie dostarcza gotowego, podłączanego-jednym-klikiem MCP connectora out-of-the-box. Dostarcza warstwę danych. Jeśli rozważasz workflow "Claude Desktop nad fakturami Pianisty" i chcesz omówić szczegóły — napisz na kontakt@pianista.tax, chętnie podzielimy się przykładowym schematem MCP server'a dla takiego przypadku. Nie oznacza to żadnego oficjalnego zobowiązania co do integracji — traktuj to jak rozmowę techniczną o możliwym stosie.

Alternatywy dla Claude + MCP

MCP to nie jedyna droga do "AI + twoje dane". Warto znać alternatywy.

• ChatGPT + Advanced Data Analyst. Wrzucasz plik CSV lub Excel do chmury OpenAI, model go analizuje. Działa dobrze dla jednorazowych zadań, ale dane wychodzą z infrastruktury firmy. Dla wrażliwych danych kontrahentów — raczej nie.
• Ollama + lokalny LLM (Llama 3.3, Mistral, Qwen). Całkowicie lokalnie, nic nie wychodzi. Kompromis: modele open-weight w kwietniu 2026 są słabsze niż Claude Opus lub GPT-4 w rozumowaniu i kodowaniu zapytań SQL. Dla prostych pytań analitycznych może wystarczyć; dla złożonych — zauważysz różnicę.
• Własny RAG z LlamaIndex, LangChain lub Haystack. Retrieval-Augmented Generation: budujesz indeks wektorowy nad dokumentami (np. fakturami, umowami, polityką kosztową), i model odpytuje go w trakcie rozmowy. Wymaga więcej inżynierii niż MCP (trzeba zadbać o embeddings, vector store, chunking). Sensowne, gdy masz dużo tekstu nieustrukturyzowanego obok faktur.
• BI + AI copilot (Power BI Copilot, Tableau Pulse). Interfejs naturalny nad hurtownią danych BI. Działa na hurtowni, którą już masz; Microsoft i Salesforce uruchamiają modele AI w swoich chmurach. Nie wszystkie firmy akceptują to ze względów prywatności.

Pytania i odpowiedzi

Czy MCP działa z ChatGPT?

Nie w tej samej formie. Model Context Protocol to otwarty standard zapoczątkowany przez Anthropic i natywnie wspierany w ekosystemie Claude (Claude Desktop, Claude Code, API). ChatGPT ma własne mechanizmy rozszerzeń: Custom GPTs, Actions (OpenAPI), wbudowany Code Interpreter. W 2025 OpenAI zapowiedziało interoperacyjność z MCP w narzędziach deweloperskich, ale dostęp u końcowego użytkownika ChatGPT nie jest identyczny z Claude Desktop. Jeśli zależy ci na prywatnych serwerach MCP odpytujących dane lokalne — Claude Desktop to w kwietniu 2026 najdojrzalszy klient.

Czy potrzebuję zgody klienta na użycie Claude Desktop na jego danych?

Zależy, co wychodzi do chmury modelu. Sam MCP server zostaje lokalny, ale wyniki tool-calli (np. lista faktur z kwotami i nazwami kontrahentów) trafiają do Claude, aby model mógł sformułować odpowiedź. To są dane wrażliwe w rozumieniu RODO. W praktyce: dla własnej firmy zgoda nie jest potrzebna (administrator danych = pracodawca), dla danych klienta (np. biuro rachunkowe pracujące na fakturach klientów) — zaktualizuj umowę powierzenia i klauzule dot. podwykonawców, ewentualnie anonimizuj kontrahentów przed zapytaniem.

Czy Pianista ma gotowy MCP server?

Status na kwiecień 2026: Pianista dostarcza fundament danych (lokalna baza faktur KSeF w SQLite lub PostgreSQL, eksport ustrukturyzowany), który łatwo opakować we własny MCP server. Gotowy connector MCP out-of-the-box — sprawdź aktualny komunikat vendora na pianista.tax lub napisz na kontakt@pianista.tax, bo roadmap może ulec zmianie. Bezpieczniej zaplanować własnego MCP server'a nad bazą Pianisty niż czekać na oficjalny release.

Czy mogę napisać własny MCP server?

Tak. Anthropic udostępnia oficjalne SDK w TypeScript i Python, plus community SDK w Go, Rust, C#, Java, Kotlin. Schemat jest prosty: definiujesz listę narzędzi (tools), każde narzędzie to funkcja o podanej sygnaturze (np. get_invoices(month: str, department: str) -> list), która wykonuje zapytanie do twojej bazy i zwraca wynik. SDK obsługuje transport (stdio dla lokalnych serwerów, HTTP+SSE dla zdalnych). W kilka godzin można zbudować server odpytujący SQLite z fakturami — startery są w repo modelcontextprotocol na GitHubie.

Jaki jest koszt Claude Desktop?

Claude Desktop jako aplikacja jest darmowy do pobrania (claude.ai/download). Użycie modelu wymaga konta — plan Free ma limity dziennej liczby wiadomości i brak dostępu do najmocniejszych modeli, plan Pro (około 20 USD miesięcznie, kwiecień 2026) odblokowuje Claude Sonnet i Opus oraz większe limity, plan Team / Enterprise dla firm ma SSO, kontrolę retencji i API dostęp. MCP działa na każdym płatnym planie. Do analitycznych zapytań nad bazą faktur Pro wystarcza większości firm.

Czy MCP tool-calle są audytowalne?

Tak, ale audyt musisz zaimplementować sam w MCP serverze. Każde wywołanie narzędzia to standardowe wejście funkcji Pythonowej lub TypeScriptowej — można je logować z timestampem, argumentami, zwróconym rozmiarem danych. Rekomendowana praktyka: JSON log per request, retencja 12 miesięcy, separacja od logu aplikacyjnego. Dla compliance SOC2 lub ISO 27001 jest to podstawa — dokumentuje kto (które konto Claude) pytał o jakie dane i kiedy.

Dalej w temacie

Trzy artykuły, które warto przeczytać obok tego:

• Automatyzacja analizy faktur KSeF — szersza perspektywa wszystkich narzędzi, nie tylko MCP
• KSeF a bezpieczeństwo danych — jakie zagrożenia ma wrażliwość danych z KSeF, jak je ograniczać
• KSeF dla controllingu — przypadek użycia, w którym MCP-like zapytania mają największy sens

Źródła techniczne: modelcontextprotocol.io — oficjalna specyfikacja i lista klientów/serwerów MCP; docs.anthropic.com — dokumentacja Anthropic (sprawdź aktualną sekcję dotyczącą MCP i Claude Desktop, URL może się zmieniać); ksef.podatki.gov.pl — dokumentacja techniczna KSeF i schemat FA(3). SDK MCP dla Pythona i TypeScripta są dostępne w oficjalnych repozytoriach modelcontextprotocol na GitHubie.