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, from_date=None, to_date=None)	Summaries of received messages, most recent first. Without a date range ISDS returns only ~90 days; pass from_date (ISO, e.g. 2024-10-01) for older ones
list_sent_messages(limit=20, from_date=None, to_date=None)	Summaries of sent messages, most recent first (same date range rules)
get_message(message_id, include_attachment_content=False)	Full received message with documents; attachment bytes are base64-encoded and only included on request
get_sent_message(message_id, include_attachment_content=False)	Same as get_message, for sent messages (IDs from list_sent_messages)
save_attachments(message_id, directory, sent=False)	Save a message's documents as files in an absolute directory on the server machine and return their paths — read attachments without base64 in the conversation; never overwrites
mark_message_read(message_id)	Mark a received message as read (write — blocked when READ_ONLY=true)
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 (write — blocked when READ_ONLY=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 (write — blocked when READ_ONLY=true)
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. Copy .env.example as a starting point:

cp .env.example .env

export DATOVKA_URL="https://ws1.mojedatovaschranka.cz/"  # optional; trailing slash required
export DATOVKA_USERNAME="..."
export DATOVKA_PASSWORD="..."
export READ_ONLY=true   # default; set false only when you intentionally want to send/mark-read

Variable	Default	Notes
DATOVKA_URL	https://ws1.mojedatovaschranka.cz/	Production username/password SOAP endpoint. Prefer the testing sandbox https://ws1.czebox.cz/ (or https://ws1.datovka-test.gov.cz/) when you have a test box. Trailing slash required.
DATOVKA_USERNAME	(required)	ISDS login username
DATOVKA_PASSWORD	(required)	ISDS login password
READ_ONLY	true	When true/1/yes, send_message, send_text_message, and mark_message_read raise ValueError

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

Testing

Structural tests (no ISDS login):

pytest tests/test_server.py

Live capability scenario (all read tools + READ_ONLY write guards):

DATOVKA_USERNAME=... DATOVKA_PASSWORD=... \
  python tests/live_capability_scenario.py

# Prefer testing sandbox when available:
DATOVKA_URL=https://ws1.czebox.cz/ DATOVKA_USERNAME=... DATOVKA_PASSWORD=... \
  python tests/live_capability_scenario.py

Exit code is 0 only when every non-skipped check passes.

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.