mcp-server-datovka

An MCP server exposing the Czech ISDS Data Box system ("Datové schránky") as tools, built on fastmcp and python3-datovka.

Tools

Tool	Description
list_received_messages(limit=20)	Summaries of received messages, most recent first
list_sent_messages(limit=20)	Summaries of sent messages, most recent first
get_message(message_id, include_attachment_content=False)	Full message with documents; attachment bytes are base64-encoded and only included on request
mark_message_read(message_id)	Mark a received message as read
send_message(recipient_box_id, subject, attachments, ...)	Send a new message; attachments is a list of dicts with filename, mime_type, is_main, and either content_base64 or file_path (a path on the machine running the server — preferred for anything but tiny files, since the bytes never have to pass through the calling LLM's context), exactly one of which must be is_main=True
send_text_message(recipient_box_id, subject, body)	Compose plain text as a PDF and send it as the message's main document — no existing file needed
find_data_box(query, limit=10)	Look up a recipient's data box ID by name, trade name, or IČO. Uses the offline seznamds directory first (fast, unlimited), falling back to the live, rate-limited ISDS search API if it's absent or finds nothing. The response includes source and data_age_days so a stale offline snapshot doesn't get presented as current.
ping()	Verify the session is alive

Messages in ISDS are envelope + document attachments, not a body text field — that's why sending "just text" (send_text_message) means rendering it to a PDF first, using the system's DejaVu Sans font so Czech diacritics render correctly.

Configuration

Credentials are read once from the environment at startup and are never tool parameters, so the LLM driving the server can't see or choose them:

export DATOVKA_URL="https://ws1.mojedatovaschranka.cz/"  # optional, this is the default; trailing slash required
export DATOVKA_USERNAME="..."
export DATOVKA_PASSWORD="..."

Install the optional seznamds package for fast, unlimited recipient lookups via find_data_box:

apt install seznamds

Without it, find_data_box still works but falls back to the live, rate-limited ISDS search API for every lookup.

Running

mcp-server-datovka

Or point an MCP client at it directly:

python -m mcp_server_datovka.server

Requirements

• libdatovka8 + python3-datovka (or pip install datovka)
• fastmcp
• python3-fpdf (fpdf2) + fonts-dejavu-core, for send_text_message
• seznamds (recommended, optional), for fast offline find_data_box lookups

License

LGPL-3.0-or-later.