{"id":"184c3c0d-3990-45e3-b760-4aab2fbd8074","slug":"mcp-datovka","kind":"mcp","name":"mcp-datovka","summary":"MCP server for Czech ISDS (datove schranky) - multi-box data message management","owner":"Sensio-cz","repoUrl":"https://github.com/Sensio-cz/mcp-datovka","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-23T13:49:36.000Z","addedAt":"2026-10-21T20:49:07.956Z","logoUrl":"https://avatars.githubusercontent.com/u/265394189?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T21:01:17.903Z","sample":false,"url":"https://conduits.dev/tools/mcp-datovka","language":"Python","transports":["stdio"],"install":{"pypi":"mcp-datovka"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# mcp-datovka\n\nMCP server for Czech ISDS (Informacni system datovych schranek) - the official Czech government digital mailbox system.\n\nEnables AI assistants (Claude, Cursor, etc.) to read, send, and manage data messages across multiple data boxes through the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## Features\n\n- **Multi-box support** - manage up to 99 data boxes from a single server\n- **Full message lifecycle** - list, read, send, and download messages with attachments\n- **Data box search** - find recipients by name, ICO, or box ID\n- **Production + sandbox** - supports both mojedatovaschranka.cz and czebox.cz test environment\n- **Stdio transport** - runs locally, no network exposure of credentials\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `datovka_list_boxes` | List all configured data boxes |\n| `datovka_list_received` | List received messages (with date filter) |\n| `datovka_list_sent` | List sent messages (with date filter) |\n| `datovka_read_message` | Read message detail with attachments |\n| `datovka_download_attachment` | Download a specific attachment (base64) |\n| `datovka_send_message` | Send a data message with attachments |\n| `datovka_search_box` | Search for a data box by name/ICO/ID |\n| `datovka_mark_read` | Mark a message as read |\n\n## Requirements\n\n- Python 3.11+\n- ISDS credentials (username + password) for each data box\n  - Obtain from [mojedatovaschranka.cz](https://www.mojedatovaschranka.cz) > Nastaveni > Moznosti prihlaseni\n\n## Installation\n\nInstall from source - the package is **not published on PyPI yet**, so\n`pip install mcp-datovka` does not work:\n\n```bash\ngit clone https://github.com/Sensio-cz/mcp-datovka.git\ncd mcp-datovka\npip install .        # pro vyvoj: pip install -e .\n```\n\n## Configuration\n\n### 1. Create `.env` file\n\nCopy `.env.example` to `.env` and fill in your credentials:\n\n```env\n# Test environment (czebox.cz) - set to \"true\" for sandbox\nDATOVKA_TEST_ENV=false\n\n# Box 1\nDATOVKA_BOX_1_ALIAS=my-company\nDATOVKA_BOX_1_ID=abc1234\nDATOVKA_BOX_1_USERNAME=your_username\nDATOVKA_BOX_1_PASSWORD=your_password\n\n# Box 2\nDATOVKA_BOX_2_ALIAS=personal\nDATOVKA_BOX_2_ID=def5678\nDATOVKA_BOX_2_USERNAME=username2\nDATOVKA_BOX_2_PASSWORD=password2\n```\n\nEach box needs 4 environment variables with a sequential number (1-99):\n- `DATOVKA_BOX_N_ALIAS` - friendly name used in tool calls\n- `DATOVKA_BOX_N_ID` - ISDS box ID (7 alphanumeric characters)\n- `DATOVKA_BOX_N_USERNAME` - ISDS login username\n- `DATOVKA_BOX_N_PASSWORD` - ISDS login password\n\n### 2. Add to your MCP client\n\n#### Claude Code / Claude Desktop\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"datovka\": {\n      \"command\": \"mcp-datovka\",\n      \"env\": {\n        \"DATOVKA_BOX_1_ALIAS\": \"my-company\",\n        \"DATOVKA_BOX_1_ID\": \"abc1234\",\n        \"DATOVKA_BOX_1_USERNAME\": \"your_username\",\n        \"DATOVKA_BOX_1_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\nOr using a `.env` file. **Careful:** it is looked up from the working directory\nof the MCP client process, not from the checkout - after `pip install .` those\nare two different places. Give the client a working directory that holds the\n`.env`, or pass the credentials in `env` as above.\n\n```json\n{\n  \"mcpServers\": {\n    \"datovka\": {\n      \"command\": \"mcp-datovka\"\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd to `.cursor/mcp.json` with the same format.\n\n## Usage examples\n\n### List received messages\n\n```\n\"Show me received messages in my-company data box\"\n```\n\nThe AI assistant calls `datovka_list_received(box_alias=\"my-company\")` and displays the results.\n\n### Send a document\n\n```\n\"Send invoice.pdf to data box abc1234 from my-company box with subject 'Invoice 2026/03'\"\n```\n\nThe assistant calls `datovka_send_message` with the file content as base64.\n\n### Search for a recipient\n\n```\n\"Find the data box for ICO 04004621\"\n```\n\nThe assistant calls `datovka_search_box(query=\"04004621\")`.\n\n### Cross-channel workflow (with Gmail MCP)\n\n```\n\"Take the attachment from the email by Novak and send it via data box to the tax office\"\n```\n\nThe assistant:\n1. Downloads the attachment from Gmail (`gmail_get_attachment_content`)\n2. Sends it via ISDS (`datovka_send_message`)\n\n## ISDS API details\n\nThis server communicates with ISDS via SOAP/HTTPS using bundled WSDL definitions from [dslib](https://github.com/yarda/dslib) (CZ.NIC).\n\n| Operation | WSDL | SOAP endpoint |\n|-----------|------|---------------|\n| List messages | `dm_info.wsdl` | `/DS/dx` |\n| Send/download messages | `dm_operations.wsdl` | `/DS/dz` |\n| Search data boxes | `db_search.wsdl` | `/DS/df` |\n\n**Authentication:** HTTP Basic Auth over HTTPS. Each box authenticates independently.\n\n**Environments:**\n\n| Environment | Base URL |\n|-------------|----------|\n| Production | `https://ws1.mojedatovaschranka.cz` |\n| Test (sandbox) | `https://ws1.czebox.cz` |\n\n## Testing with sandbox\n\n1. Log in to [mojedatovaschranka.cz](https://www.mojedatovaschranka.cz)\n2. Go to Nastaveni > Pro vyvojare\n3. Create test data boxes (up to 4)\n4. Set `DATOVKA_TEST_ENV=true` in `.env`\n5. Use sandbox credentials\n\n## Security\n\n### Two-step send confirmation (HITL)\n\nThe `datovka_send_message` tool implements a **mandatory two-step confirmation flow**:\n\n1. **First call** (`confirmed=false`, default) - returns a preview of the message (sender, recipient, subject, attachments) without sending anything\n2. **Second call** (`confirmed=true`) - actually sends the message, but only after the AI has shown the preview to the user and received explicit approval\n\nThis ensures that no data message is ever sent without human approval, regardless of the AI assistant's behavior.\n\n### Other security measures\n\n- Credentials are stored in `.env` (gitignored) or passed via environment variables\n- Communication with ISDS is always over HTTPS/TLS\n- The server runs locally via stdio - no network ports are opened\n- No message content is logged - only metadata (subject, sender, timestamp)\n- Each box authenticates independently - compromising one box does not affect others\n\n## Legal notice\n\nData messages (datove zpravy) sent through ISDS have the **legal effect of delivery by registered mail** under Czech law (Act No. 300/2008 Coll.). Use this tool responsibly and always verify the recipient before sending.\n\n## License\n\nMIT\n\n## Credits\n\n- WSDL definitions from [dslib](https://github.com/yarda/dslib) by CZ.NIC (LGPL)\n- Built with [zeep](https://github.com/mvantellingen/python-zeep) SOAP client\n- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic\n"}