Pierwszy działający efekt pokazuję zwykle w 2-4 tygodnie. Zamiast slajdów i obietnic dostajesz rozwiązanie, które od razu możesz przetestować u siebie w firmie.

Ile kosztuje współpraca?

Szybki start produktu to od 15 000 PLN jednorazowo. Później dostępna jest opieka na abonament (od 5 000 PLN/mies) na rozwój i utrzymanie, oraz pakiet automatyzacji (od 3 000 PLN/mies) na kolejne usprawnienia. Dokładną wycenę podaję po 30-minutowej rozmowie.

Nie znam się na technologii, dam radę?

Tak. Rozmawiamy po ludzku, bez żargonu. Ty mówisz, co Cię uwiera w firmie, a ja zajmuję się całą techniczną stroną i dostarczam gotowe do użycia narzędzie.

Dla kogo jest ta oferta?

Dla firm, które tracą godziny na powtarzalną, ręczną pracę (wyceny, raporty, odpowiedzi, obsługa zamówień) i chcą to usprawnić bez budowania własnego zespołu programistów.

Jak zacząć współpracę?

Umów bezpłatną rozmowę na https://bartoszgaca.pl/rozmowa/. Opowiadasz, co chcesz usprawnić, a Ty dostajesz konkretny plan: co da się zrobić, ile to zajmie i ile kosztuje.

MCP dla ZUS: dokumenty KEDU i PUE ZUS obsługiwane przez AI

Otwarty serwer MCP, przez który Claude albo inny klient MCP przygotowuje i sprawdza dokumenty ZUS w formacie KEDU, a w zalogowanej sesji PUE odczytuje status wysłanych zestawów. Projekt jest w wersji alpha i ma jasno opisane granice.

Branża: Księgowość, kadry i płace, jednoosobowe działalności

W skrócie

Otwarty serwer MCP dla ZUS, licencja MIT
30 narzędzi zarejestrowanych w serwerze MCP
KEDU 5.6 generowane i walidowane offline, bez akredytacji
Status alpha v0.1.0, opisany moduł po module

O projekcie

ZUS nie publikuje SDK, a praca z dokumentami ubezpieczeniowymi to pliki XML w formacie KEDU, osobne kanały wysyłki i logowanie do PUE z kodem SMS. mcp-zus to serwer MCP, przez który model językowy, na przykład Claude albo GPT, przygotowuje i sprawdza te dokumenty, a w trybie przeglądarki odczytuje dane z zalogowanej sesji PUE ZUS.

Wyzwanie

Trzeba było dać AI dostęp do ZUS wszędzie tam, gdzie da się to zrobić bez akredytacji, i uczciwie oznaczyć miejsca, które jej wymagają. Do tego nic wrażliwego nie mogło przechodzić przez serwer: ani klucz do podpisu kwalifikowanego, ani hasło do PUE.

Cele

Generować, parsować i walidować dokumenty KEDU 5.6 bez połączenia z ZUS
Obsłużyć wnioski OK-WUD dla uprawnionych instytucji
Pozwolić AI czytać dane z PUE bez przejmowania logowania
Nigdy nie wczytywać klucza prywatnego użytkownika

Wyzwania techniczne

Podpis kwalifikowany zostaje u użytkownika

Serwer przygotowuje dane do podpisu i osadza gotowy podpis w dokumencie, ale nigdy nie wczytuje klucza prywatnego. Podpisujesz lokalnie, na przykład w Szafirze albo Certum.

PUE bez publicznego API

Tryb Browser Companion doczepia się przez CDP do Chrome, w którym logujesz się ręcznie loginem i kodem SMS. Wykonuje tylko odczyty i nieinwazyjne operacje.

Dane osobowe w logach

Logi maskują NIP i PESEL na poziomach INFO i WARN, a sekrety są w zmiennych środowiskowych, poza repozytorium.

Rozwiązanie i wdrożenie

KEDU offline

Prosisz Claude o dokument, na przykład miesięczną deklarację DRA dla jednoosobowej działalności, a serwer zwraca zwalidowany XML KEDU 5.6 gotowy do podpisu u Ciebie.

OK-WUD z importem danych

Kreator wniosków o udostępnienie danych buduje XML według oficjalnego wzoru i przyjmuje dane z plików XLSX, XLS, CSV, ODS i XML.

Browser Companion dla PUE

Logujesz się do PUE sam, a AI w tej samej sesji sprawdza na przykład status ostatnio wysłanych zestawów dokumentów.

Rezultaty

AI pracuje na dokumentach ZUS

Zamiast ręcznie składać XML, opisujesz, czego potrzebujesz, i dostajesz dokument zgodny ze schematem KEDU.

Bezpieczeństwo z założenia

Klucz do podpisu i logowanie do PUE zostają po Twojej stronie. Serwer ich nie widzi.

Wnioski

Granice opisane wprost

Każdy moduł ma status: co działa w pełni, co jest szkieletem i czego wymaga. Wysyłka przez EWD i produkcyjne OK-WUD potrzebują akredytacji w ZUS.

Zakres

Dokumenty KEDU offline
Wnioski OK-WUD
Tryb PUE Browser Companion
Podpis po stronie użytkownika

Technologie

MCP
Python 3.11
FastMCP
Playwright

Projekt open source

Język: Python 3.11+. Licencja: MIT. Status: alpha v0.1.0.

Instalacja

git clone https://github.com/gacabartosz/mcp-zus.git && cd mcp-zus
uv sync --all-extras
uv run mcp-zus

Konfiguracja klienta MCP

{
  "mcpServers": {
    "zus": {
      "command": "uv",
      "args": ["--directory", "/sciezka/do/mcp-zus", "run", "mcp-zus"],
      "env": { "PUE_CDP_URL": "http://localhost:9222" }
    }
  }
}

Przykład użycia

W Claude Code poproś o deklarację dla swojej działalności. Serwer wywoła narzędzie KEDU i zwróci XML do podpisu.

> Zbuduj DRA na maj 2026 dla mojej jednoosobowej działalności, podstawa preferencyjna
# kedu.build_jdg_monthly() zwraca zwalidowany XML KEDU 5.6

Najczęstsze pytania

Czy mcp-zus wysyła dokumenty do ZUS za mnie?

Produkcyjna wysyłka przez EWD wymaga akredytacji w ZUS, więc w wersji alpha moduł EWD ma gotowy interfejs, ale nie wysyła. Dokumenty KEDU generujesz i walidujesz offline, a podpisujesz u siebie.

Czy serwer zna moje hasło do PUE?

Nie. Logujesz się ręcznie w przeglądarce, z kodem SMS. Serwer tylko doczepia się do otwartej sesji i nie obsługuje danych logowania.

Czy mogę używać go produkcyjnie?

Projekt jest w wersji alpha. README wprost zaleca własne testy na własnych danych przed użyciem w produkcji.

Z jakimi programami działa?

Z każdym klientem MCP, na przykład z Claude Code i Claude Desktop. Serwer działa lokalnie przez stdio.

Wszystkie case studies