isir-mcp – MCP server pro insolvenční rejstřík (isir.justice.cz)

English summary. A local Model Context Protocol server (stdio) for the Czech public insolvency register ISIR. It looks up debtors and proceedings via the official SOAP web services of the Ministry of Justice, lists all events and documents of a case from the public case-detail page, downloads the PDFs, extracts their text and OCRs scanned pages (Tesseract, Czech), unpacks PDF portfolios and offers full-text search across a case. It enforces the register's published rate limits. Czech documentation follows.

Lokální MCP server pro Claude Desktop, Claude Code a další MCP klienty. Umožňuje asistentovi pracovat s úplným obsahem všech dokumentů insolvenčního řízení – včetně skenů.

Nástroje

Server nepoužívá webový vyhledávací formulář ISIR (je chráněn CAPTCHA). Lustrace jde výhradně přes oficiální webovou službu MSp určenou pro strojový přístup; detail řízení a dokumenty se čtou z veřejných URL bez přihlášení.

Related MCP server: rejestr-io-mcp

Limity a chování

Podmínky provozu ISIR povolují max. 50 požadavků/min a 3 000/den. Server vynucuje výchozí 1 požadavek / 1,5 s (40/min) a 2 500/den; denní počítadlo je uložené v cache a přežije restart. Při vyčerpání vrátí nástroj chybu – limit nikdy nepřekročí.

Vše stažené (HTML detailů na 1 h, PDF, extrahovaný text, metadata) je v cache ~/.isir-mcp/cache (změna přes ISIR_CACHE_DIR). Cesty k souborům jsou ve výstupu nástrojů, takže klient může s PDF/TXT dále pracovat jako s běžnými soubory.

Cache obsahuje osobní údaje dlužníků z veřejného rejstříku. Zacházejte s ní jako s ostatními spisovými materiály (přístupová práva, výmaz po skončení věci).

Instalace

A) Claude Desktop – jedním kliknutím (.mcpb)

1. Stáhněte isir-mcp-X.Y.Z.mcpb z Releases.

2. Otevřete soubor dvojklikem (nebo Claude Desktop → Settings → Extensions → Advanced settings → Install Extension…).

3. V nastavení rozšíření volitelně zadejte složku cache, cestu k Tesseractu, jazyky OCR, denní limit a kontakt.

Balíček používá runtime uv – Claude Desktop si sám stáhne Python i závislosti, nic dalšího není potřeba. Pro OCR skenovaných dokumentů nainstalujte Tesseract OCR s českými daty (viz níže) a cestu k tesseract.exe zadejte v nastavení rozšíření.

Sestavení balíčku ze zdrojů: python scripts/build_mcpb.py → dist/isir-mcp-X.Y.Z.mcpb (použije oficiální CLI @anthropic-ai/mcpb, je-li k dispozici npx).

B) Ručně (Claude Code, jiní MCP klienti, vývoj)

Požadavky: Python 3.10+ a Tesseract OCR s českými daty.

• Windows: instalátor UB Mannheim → Additional language data → Czech. Výchozí cesta C:\Program Files\Tesseract-OCR\tesseract.exe.

• macOS: brew install tesseract tesseract-lang

• Debian/Ubuntu: sudo apt install tesseract-ocr tesseract-ocr-ces

git clone https://github.com/marshall1727/isir-mcp.git
cd isir-mcp
python -m venv .venv
# Windows: .\.venv\Scripts\pip install -e .    |  macOS/Linux: .venv/bin/pip install -e .

Na Windows lze místo toho spustit install.ps1, který vytvoří prostředí, nainstaluje balíček, spustí offline testy a vygeneruje blok konfigurace pro Claude Desktop.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) nebo ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "isir": {
      "command": "C:\\cesta\\k\\isir-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "isir_mcp.server"],
      "env": {
        "TESSERACT_CMD": "C:\\Program Files\\Tesseract-OCR\\tesseract.exe",
        "ISIR_OCR_LANG": "ces+eng",
        "ISIR_CACHE_DIR": "C:\\cesta\\k\\isir-cache",
        "ISIR_CONTACT": "vas@email.cz"
      }
    }
  }
}

Po restartu ověřte: „Zavolej isir_stav_serveru“ → ocr_dostupne: true.

Claude Code

claude mcp add isir -e TESSERACT_CMD="C:\Program Files\Tesseract-OCR\tesseract.exe" -- <cesta>/.venv/Scripts/python.exe -m isir_mcp.server

Ověření proti živému ISIR

.venv/bin/python tests/live_smoke.py     # ~6 požadavků: lustrace → detail → oddíl B → text dokumentu

Proměnné prostředí

Typický postup v konverzaci

1. isir_lustrace(ico="12345678") → spisová značka + detailId

2. isir_detail_rizeni("KSOS 25 INS 10525/2016") → stav, správce, počty událostí

3. isir_udalosti(rizeni=..., oddil="B", hledat="usnesení") → ID dokumentů

4. isir_text_dokumentu(dokument_id="58657721") → plný text (OCR podle potřeby)

5. isir_hledat_v_dokumentech(rizeni=..., dotaz="zajištěný věřitel", oddily="B,P", max_dokumentu=30)

Release

Hotové balíčky jsou v záložce Releases: isir-mcp-X.Y.Z.mcpb (rozšíření pro Claude Desktop), isir_mcp-X.Y.Z-py3-none-any.whl (instalace pip install <soubor>.whl), sdist a zdrojový zip. Release vytváří GitHub Actions automaticky po pushi tagu vX.Y.Z; verze tagu musí odpovídat version v pyproject.toml. Lokálně to zařídí publish.ps1.

Vývoj

pip install -e ".[dev]"
pytest            # offline testy parserů (fixture HTML)
ruff check .

Struktura: ws.py (SOAP služby), detail.py (parser detailu řízení), documents.py (PDF, OCR, portfolia), ratelimit.py, server.py (MCP nástroje).

Známá omezení

• Oddíl P velkých řízení (tisíce přihlášek) je jedna velká HTML stránka; načtení trvá, ale jde o 1 požadavek. Fulltext přes stovky dokumentů respektuje limity – počítejte s minutami.

• Nová podoba rejstříku (eisir.justice.cz) byla v době vývoje v ověřovacím provozu bez dat; server používá stávající ISIR. Změní-li MSp HTML detailu, upravte isir_mcp/detail.py (testy ve tests/ to odhalí).

• Kvalita OCR závisí na kvalitě skenu; ocr="force" pomůže u PDF s poškozenou textovou vrstvou.

Právní poznámka

Insolvenční rejstřík je veřejně přístupný informační systém veřejné správy (§ 419 a násl. insolvenčního zákona); každý má právo do něj nahlížet a pořizovat kopie a výpisy. Tento software není produktem Ministerstva spravedlnosti. Uživatel odpovídá za dodržení Podmínek provozu ISIR a za nakládání s osobními údaji získanými z rejstříku.

Licence

MIT – viz LICENSE.