# Mcp Zus

> First public MCP server for Polish ZUS / PUE — KEDU 5.6, OK-WUD, EWD, ePUAP, browser companion. By Bartosz Gaca.

- **Type:** MCP server
- **Install:** `agentstack add mcp-gacabartosz-mcp-zus`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gacabartosz](https://agentstack.voostack.com/s/gacabartosz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gacabartosz](https://github.com/gacabartosz)
- **Source:** https://github.com/gacabartosz/mcp-zus
- **Website:** https://github.com/gacabartosz/mcp-zus

## Install

```sh
agentstack add mcp-gacabartosz-mcp-zus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-zus

> **Pierwsze publiczne MCP (Model Context Protocol) dla polskiego ZUS / PUE ZUS.**
> Pokrywa KEDU, EWD, OK-WUD, ePUAP oraz tryb "browser companion" do zalogowanej sesji PUE.

[](LICENSE)
[](https://www.python.org/downloads/)
[]()

## Co to jest

`mcp-zus` to serwer MCP, który pozwala LLM-owi (Claude, GPT, dowolnemu klientowi MCP) operować na ZUS:

- **KEDU 5.6** — generować, parsować i walidować dokumenty XML (DRA, RCA, RSA, ZUA, ZWUA, ZIUA, ZCNA, ...) **offline**, bez akredytacji.
- **EWD** — wysyłać KEDU do ZUS przez oficjalny SOAP po stronie płatnika (po akredytacji).
- **OK-WUD** — wnioski o udostępnienie danych dla **uprawnionych instytucji** (sądy, komornicy, NFZ, KRUS, banki, ...) przez `pue.zus.pl:8100`.
- **ePUAP** — wysyłka pism na skrzynkę ZUS (`/ZUS/esp`) przez WS-Skrytka.
- **PUE Browser Companion** — pragmatyczny tryb: logujesz się ręcznie w Chrome (login + SMS), MCP doczepia się do sesji przez CDP i robi czytanie + nieinwazyjne operacje. **Bez akredytacji ZUS.**

## Status modułów

| Moduł | Status | Co działa 100% | Czego wymaga |
|-------|--------|----------------|--------------|
| `kedu` envelope | ✅ | XSD-valid envelope: `` + `` z `program`/`ID_KEDU`/`data_utworzenia_KEDU`. Walidator (lxml + XSD), parser, SHA-256 digest. | offline |
| `kedu` inner sections | 🟡 WIP | Generuje `ZUSDRA`/`ZUSZUA`/`ZUSZWUA`/`ZUSZIUA`/`ZUSZCNA` z payerem i podstawowymi danymi. **Sekcje I-XIV z polami pozycyjnymi `...` zgodnie z formularzem Płatnika to iterative roadmap (v0.2).** | offline |
| `okwud` builder + importers | ✅ | Pełny XML wg `crd.gov.pl/wzor/2020/12/29/10229`, 60+ kodów instytucji, 5 formatów importu (XLSX/XLS/CSV/ODS/XML) | offline |
| `okwud` SOAP client | 🟡 scaffold | WSDL endpoint stały, struktura sesji `pobierzOswiadczenie` znana | cert kwalifikowany + uprawnienia uprawnionej instytucji |
| `crypto` BYO key | ✅ | `prepare_signing_payload` (C14N + SHA-256 digest), `attach_signature` (osadza ``); server NIGDY nie czyta klucza | klucz po stronie usera |
| `pue` browser companion | 🟡 alpha | Playwright + CDP attach do running Chrome'a, page-object pattern, MCP nigdy nie obsługuje credentials | Chrome `--remote-debugging-port=9222` + ręczne login + kalibracja selektorów na żywej sesji |
| `ewd` (płatnik SOAP) | 🟡 scaffold | Interfejs i sygnatury gotowe | akredytacja u ZUS dla produkcji |
| `epuap` (WS-Skrytka) | 🟡 scaffold | Interfejs gotowy | cert MAC dla SOD |
| `employee` orchestrator | ✅ | High-level `register/deregister/update/add_family_member` opakowuje KEDU builder | offline |
| MCP server (stdio) | ✅ | 30 tooli zarejestrowanych przez FastMCP, smoke-tested po stdio JSON-RPC | offline |

## Quickstart

```bash
# 1. Klon
git clone https://github.com/gacabartosz/mcp-zus.git && cd mcp-zus

# 2. Instalacja (uv recommended)
uv sync --all-extras

# 3. Uruchom MCP server
uv run mcp-zus

# 4. Zarejestruj w Claude Code (~/.claude.json) lub Claude Desktop:
# {
#   "mcpServers": {
#     "zus": {
#       "command": "uv",
#       "args": ["--directory", "/sciezka/do/mcp-zus", "run", "mcp-zus"],
#       "env": { "PUE_CDP_URL": "http://localhost:9222" }
#     }
#   }
# }
```

## Przykład — KEDU offline (Faza 1)

```bash
# W Claude:
> Zbuduj DRA na maj 2026 dla NIP 1234563218, samozatrudniony JDG, podstawa preferencyjna
# → kedu.build_jdg_monthly()
# → zwraca walidowany XML KEDU 5.6 gotowy do podpisu kwalifikowanego u Ciebie lokalnie
```

## Przykład — PUE Browser Companion (Faza 1.5)

```bash
# 1. Uruchom Chrome z CDP enabled:
open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-pue-mcp"

# 2. Zaloguj się ręcznie na pue.zus.pl (login + SMS)

# 3. W Claude:
> Sprawdź status moich ostatnich 5 zestawów dokumentów wysłanych do ZUS
# → pue.attach() → pue.list_dokumenty() → pue.get_zestaw_status() x 5
```

## Lista narzędzi MCP

Patrz [`docs/tools.md`](docs/tools.md) dla pełnej dokumentacji 40+ tooli.

## Bezpieczeństwo

- **MCP nigdy nie wczytuje klucza prywatnego.** Wszystkie operacje podpisu zwracają payload do podpisu lokalnego u usera (Szafir, Certum, `signxml` lokalnie).
- **MCP nigdy nie loguje się sam do PUE.** Login + SMS pozostaje 100% po stronie usera; tryb `pue` jedynie *attachuje się* do otwartej sesji Chrome.
- **Sekrety w env** — patrz `.env.example`. **Nigdy** nie commituj `.env`, certyfikatów, kluczy.
- **Logi** maskują NIP/PESEL na poziomie INFO/WARN.

## Prawne ramy

- Ustawa o systemie ubezpieczeń społecznych — [`isap.sejm.gov.pl/.../WDU20250000350`](https://isap.sejm.gov.pl/isap.nsf/DocDetails.xsp?id=WDU20250000350).
- eIDAS (Rozporządzenie 910/2014) — wymóg podpisu kwalifikowanego dla EWD.
- Regulamin PUE ZUS — moduł `pue` jest narzędziem ergonomicznym dla pojedynczego usera, **nie batch-processorem**. Używaj zgodnie z regulaminem.
- ZUS oficjalnie nie publikuje SDK; produkcyjne EWD/OK-WUD wymaga indywidualnej akredytacji u ZUS.

## Status: Alpha v0.1.0

Projekt jest w fazie alpha. **Nie używaj produkcyjnie bez własnych testów na własnych danych.** Jeśli znajdziesz błąd — issue. Jeśli chcesz pomóc — PR welcome.

### Co wymaga jeszcze pracy w v0.2

1. **KEDU inner section mapping** — dla pełnej XSD-walidacji DRA/ZUA/RCA każda sekcja (I, II, ..., XIV) musi mapować pola pozycyjne `...` dokładnie wg `Załącznik 1 — Zakres informacyjny dokumentów ubezpieczeniowych ZUS` (BIP ZUS). Aktualne builders generują strukturę uproszczoną — envelope jest XSD-valid, inner sekcje są nazwane semantycznie ale nie pozycyjnie.
2. **PUE selector calibration** — selektory w `src/mcp_zus/pue/selectors.py` to educated guesses; finalna kalibracja po pierwszym `pue.attach()` na zalogowanej sesji (DevTools → Copy Selector → wklej do `selectors.py`).
3. **EWD/OK-WUD live calls** — wymaga akredytacji u ZUS; interfejsy i WSDL gotowe.
4. **JDG monthly DRA: aktualne podstawy z GUS** — obecnie zaszyte w `kedu/jdg.py`; w v0.2 czytane z aktualnego komunikatu Prezesa GUS.

## License

MIT © 2026 Bartosz Gaca

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gacabartosz](https://github.com/gacabartosz)
- **Source:** [gacabartosz/mcp-zus](https://github.com/gacabartosz/mcp-zus)
- **License:** MIT
- **Homepage:** https://github.com/gacabartosz/mcp-zus

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gacabartosz-mcp-zus
- Seller: https://agentstack.voostack.com/s/gacabartosz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.