Skip to main content

MCP for ZUS: KEDU documents and the PUE portal handled by AI

An open-source MCP server that lets Claude or any MCP client prepare and validate documents for ZUS, Poland's social insurance institution, in the KEDU format, and read the status of submitted batches in a logged-in PUE session. The project is in alpha and states its limits clearly.

Industry: Accounting, payroll, sole proprietors

In short

  • Open-source MCP server for ZUS, MIT license
  • 30 tools registered in the MCP server
  • KEDU 5.6 generated and validated offline, no accreditation needed
  • Alpha v0.1.0, status described module by module

About the project

ZUS does not publish an SDK, and working with insurance documents means XML files in the KEDU format, separate submission channels and logging in to the PUE portal with an SMS code. mcp-zus is an MCP server through which a language model such as Claude or GPT prepares and checks these documents and, in browser mode, reads data from a logged-in PUE ZUS session.

The challenge

The goal was to give AI access to ZUS wherever that is possible without accreditation, and to mark honestly the places that do require it. Nothing sensitive could pass through the server: neither the qualified signature key nor the PUE password.

Goals

  • Generate, parse and validate KEDU 5.6 documents without connecting to ZUS
  • Support OK-WUD data requests for authorised institutions
  • Let AI read PUE data without taking over the login
  • Never load the user's private key

Technical challenges

The qualified signature stays with the user

The server prepares the signing payload and embeds the finished signature in the document, but it never loads the private key. You sign locally, for example in Szafir or Certum.

PUE has no public API

Browser Companion mode attaches over CDP to a Chrome window in which you log in yourself with a password and SMS code. It only reads data and performs non-invasive operations.

Personal data in logs

Logs mask NIP and PESEL numbers at INFO and WARN level, and secrets live in environment variables, outside the repository.

Solution and implementation

Offline KEDU

You ask Claude for a document, for example the monthly DRA declaration for a sole proprietorship, and the server returns validated KEDU 5.6 XML ready for you to sign.

OK-WUD with data import

The data request builder produces XML according to the official template and accepts input from XLSX, XLS, CSV, ODS and XML files.

Browser Companion for PUE

You log in to PUE yourself, and AI uses the same session to check, for example, the status of recently submitted document batches.

Results

AI works on ZUS documents

Instead of assembling XML by hand, you describe what you need and get a document that matches the KEDU schema.

Secure by design

The signing key and the PUE login stay on your side. The server never sees them.

Takeaways

Limits stated plainly

Every module has a status: what works fully, what is a scaffold and what it requires. Submission via EWD and production OK-WUD need accreditation from ZUS.

Scope

  • Offline KEDU documents
  • OK-WUD requests
  • PUE Browser Companion mode
  • Signing stays with the user

Technologies

  • MCP
  • Python 3.11
  • FastMCP
  • Playwright

Open-source project

Language: Python 3.11+. License: MIT. Status: alpha v0.1.0.

Installation

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

MCP client configuration

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

Usage example

In Claude Code, ask for a declaration for your business. The server calls the KEDU tool and returns XML for signing.

> Build the DRA for May 2026 for my sole proprietorship, preferential base
# kedu.build_jdg_monthly() returns validated KEDU 5.6 XML

Frequently asked questions

Does mcp-zus submit documents to ZUS for me?

Production submission via EWD requires accreditation from ZUS, so in the alpha the EWD module has a ready interface but does not submit. You generate and validate KEDU documents offline and sign them yourself.

Does the server know my PUE password?

No. You log in manually in the browser, with an SMS code. The server only attaches to the open session and never handles credentials.

Can I use it in production?

The project is in alpha. The README explicitly recommends your own tests on your own data before any production use.

Which tools does it work with?

Any MCP client, for example Claude Code and Claude Desktop. The server runs locally over stdio.

All case studies