EZD via AI: an MCP server for a public office document system
An open-source MCP server that gives Claude access to the EZD PUW document management API used in Polish public administration: cases, documents, correspondence, ePUAP and e-Delivery. A clerk describes the task in a sentence and AI carries it out in the document system.
Industry: Public administration, government offices
In short
- Open-source MCP server for EZD PUW, MIT license
- 91 MCP tools grouped by system module
- Works in Claude Desktop and Claude Code
- SHA256 token authentication on every request
About the project
EZD PUW is an electronic document management system used in Polish public administration. It has an extensive API, but using it requires knowing its modules, identifiers and authentication scheme. ezd-puw-mcp wraps that API in MCP tools that a language model can call.
The challenge
A clerk should not have to learn an API to open a case, register an outgoing letter or check incoming ePUAP messages. The system's programming interface had to become tools that AI calls when asked in a plain sentence.
Goals
- Cover the EZD PUW API modules: cases, documents, correspondence, staff
- Support ePUAP and e-Delivery
- Hide authentication from the user
- Run locally in Claude Desktop and Claude Code
Technical challenges
A token computed for every request
EZD PUW requires a new GUID for every call and a SHA256 hash of the GUID, the application token and the current hour. The server computes this itself and adds the right headers.
Several sets of endpoints
The system has separate API modules, including Api1 and Api3 and modules for documents, folders and staff. Tools are grouped the same way as the system's modules, so AI picks the right call.
Solution and implementation
Cases and folders
Creating, editing, forwarding, sharing, closing and reopening cases, and searching within them.
Correspondence, ePUAP and e-Delivery
Registering outgoing correspondence and changing its status, registering and searching incoming ePUAP messages and registering e-Deliveries.
Staff, filing plan and archive
Managing staff and workflow templates, RWA filing numbers, making documents immutable in the blockchain module and importing migration packages.
Results
A document system you run with a sentence
Instead of clicking through modules, you describe the task and AI calls the right EZD tool.
One entry point to the API
All system modules are available from one MCP server, configured once.
Takeaways
MCP for public administration
Government systems have APIs, but few integrators use them. An MCP server opens them to anyone who can describe the task.
Scope
- Cases and folders
- Documents and correspondence
- ePUAP and e-Delivery
- Staff and workflows
Technologies
- MCP
- TypeScript
- Node.js 20
- EZD PUW API
Open-source project
Language: TypeScript, Node.js 20+. License: MIT.
Installation
git clone https://github.com/gacabartosz/ezd-puw-mcp.git
cd ezd-puw-mcp
npm install
npm run buildMCP client configuration
{
"mcpServers": {
"ezd-puw": {
"command": "node",
"args": ["/absolute/path/to/ezd-puw-mcp/dist/index.js"],
"env": {
"EZD_HOST": "ezd.your-office.gov.pl",
"EZD_APP_TOKEN": "your-app-token"
}
}
}
}Usage example
Ask Claude for today's ePUAP messages. The server uses the inflow search tool from the Api3 module.
> Show today's incoming ePUAP messages
# ezd_api3_search_epuap_inflowFrequently asked questions
What is ezd-puw-mcp for?
It connects AI to the EZD PUW system. You ask Claude, for example, to register a letter or find incoming ePUAP messages, and the server calls the matching API tool.
Where do I get the application token?
You get the application token in the EZD admin panel and put it in the EZD_APP_TOKEN variable in the server configuration.
Where does the server run?
Locally, over stdio, and it connects directly to the EZD server set in the configuration. The content of your requests goes to the AI model you use.
How many tools does the server have?
91, grouped by system module: cases, documents, correspondence, staff, ePUAP and more.