MCP server pro AI asistenty

Model Context Protocol je otevřený standard, kterým se AI asistenti připojují k externím systémům. MCP server iÚčta zpřístupní účetní data přímo v Claude Desktop, Claude Code, ChatGPT desktopu, Codex CLI a dalších MCP klientech – asistent pak nemusí znát REST API, dostane pojmenované nástroje.

Nástroje se generují z téže specifikace jako reference, takže se s API nerozejdou. Nástroj se jmenuje stejně jako operace v referenci: createInvoiceIssued odpovídá stránce Vytvoření faktury vydané.

Co server umí

Server vystavuje všechny operace API kromě evidence v EET: seznamy a detaily, číselníky a profil firmy, zakládání i editaci dokladů, kontaktů, plateb a skladových pohybů, zaúčtování, mazání, generování odkazů pro sdílení, odesílání dokladů e-mailem, stahování PDF a příloh i nahrávání souborů.

Evidence v EET zůstává mimo: odesílá se na Finanční správu, vzít zpět ji nejde a evidence tržeb skončila v roce 2023. Zavolat ji jde API přímo, klíč je pro obojí stejný.

U operací, které v účetnictví nejdou vzít zpět – editace a mazání – si server řekne o potvrzení sám. Nástroj nese pole potvrzeni a klient je má před zavoláním zobrazit jako dialog. Stojí to na elicitation: klient ji musí umět a ohlásit, jinak se dialog nezobrazí a nástroj se zavolá rovnou. Na straně serveru je potřeba 0.5.0 nebo novější (staví na MCP SDK 1.23.0, starší verze pole tiše zahazovaly).

Všechny zapisovací nástroje navíc nesou v tools/list pole _meta (anthropic/requiresUserInteraction), takže klient pozná zápis od čtení, aniž by musel číst readOnlyHint.

Označení je ale nápověda klientovi, ne zámek:

Klient	Chování před zápisem
Claude Code	zeptá se před každým voláním zapisovacího nástroje
Claude Desktop	dialog nezobrazí, jedinou ochranou je režim read-only
ostatní MCP klienti	podle toho, zda podporují elicitation – ověřte si to

Když si nejste jistí, co váš klient umí, nastavte read-only a otestujte to na zkušební firmě. Režim se vyplňuje do pole Režim v instalačním dialogu balíku, u ostatních klientů do proměnné IUCTO_MCP_MODE. Obojí je popsané níž.

Instalace a nastavení

Nejdřív si vygenerujte API klíč v aplikaci pod Nastavení → Nastavení API. Budete ho potřebovat u obou postupů.

Claude Desktop

Stáhněte si balík iucto-mcp-server.mcpb a soubor otevřete. Claude Desktop ukáže instalační dialog se třemi poli: API klíč, složka pro stažené doklady a Režim. Do režimu se vyplňuje full (předvyplněný, všechny nástroje), nebo read-only – jinde než tady si v Claude Desktopu režim nenastavíte, tabulka proměnných níž je pro Claude Code a konfigurační soubor Desktop nepoužívá. Když chcete jistotu, že asistent nic nepřepíše ani nesmaže, přepište pole na read-only. Tím instalace končí: balík si nese své závislosti a Node si přináší Claude Desktop, takže nemusíte nic doinstalovávat ani ručně upravovat konfigurační soubor.

Claude Code a ostatní MCP klienti

Balíček je na veřejném npm, takže nepotřebuje přihlášení ani .npmrc. Vyžaduje Node.js 20 nebo novější.

claude mcp add iucto \
  -e IUCTO_API_KEY=váš-klíč \
  -- npx -y @iucto.cz/iucto-mcp-server

Klienti, které se nastavují souborem, berou tentýž příkaz:

{
  "mcpServers": {
    "iucto": {
      "command": "npx",
      "args": ["-y", "@iucto.cz/iucto-mcp-server"],
      "env": { "IUCTO_API_KEY": "váš-klíč" }
    }
  }
}

ChatGPT desktop a Codex CLI

ChatGPT desktop, Codex CLI i rozšíření do IDE sdílejí jedno nastavení v ~/.codex/config.toml, takže server stačí přidat jednou. Potřebujete Node.js 20 nebo novější.

V ChatGPT desktopu otevřete Settings → MCP servers → Add server, zvolte transport STDIO a vyplňte:

Pole	Hodnota
název	iucto
příkaz	npx
argumenty	-y a @iucto.cz/iucto-mcp-server – dva samostatné argumenty
proměnné prostředí	IUCTO_API_KEY = váš klíč, případně IUCTO_MCP_MODE = read-only

V terminálu totéž udělá Codex CLI:

codex mcp add iucto \
  --env IUCTO_API_KEY=váš-klíč \
  --env IUCTO_MCP_MODE=read-only \
  -- npx -y @iucto.cz/iucto-mcp-server

Nebo to zapište do ~/.codex/config.toml ručně:

[mcp_servers.iucto]
command = "npx"
args = ["-y", "@iucto.cz/iucto-mcp-server"]
startup_timeout_sec = 60

[mcp_servers.iucto.env]
IUCTO_API_KEY = "váš-klíč"
IUCTO_MCP_MODE = "read-only"

startup_timeout_sec prodlužuje výchozích 10 sekund: při prvním spuštění si npx balíček teprve stahuje a nestihl by to. Režim read-only je v ukázkách záměrně, na první vyzkoušení; pro zakládání a úpravy dokladů ho změňte na full, nebo řádek smažte.

Ověření: po uložení nastavení restartujte server (v desktopu přepínačem u serveru, v CLI novým sezením) a zadejte /mcp – server iucto má být připojený se seznamem nástrojů. Pak se zeptejte třeba „Jak se jmenuje moje firma v iÚčtu?“, asistent zavolá getCompanyProfile.

Když se server nespustí:

• Server hned skončí a v nastavení je "-y @iucto.cz/…" – přepínač a název balíčku jsou v jednom argumentu. Rozdělte je na dva.
• ENOENT / npx nenalezen – aplikace spuštěná z Finderu nebo nabídky Start nemusí vidět PATH z terminálu. Do command dejte absolutní cestu, kterou vypíše which npx (na Windows where npx).

ChatGPT na webu

Tohle nastavení platí jen pro aplikace na vašem počítači. ChatGPT na webu spouštět lokální příkazy neumí, potřebuje vzdálený MCP server přes HTTPS s přihlášením – ten zatím nenabízíme.

Proměnné prostředí

Proměnná	Povinná	Výchozí	Význam
IUCTO_API_KEY	ano	–	hodnota hlavičky X-Auth-Key
IUCTO_API_BASE	ne	https://online.iucto.cz/api/1.3	jiná instance API
IUCTO_DOWNLOAD_DIR	ne	dočasný adresář systému	kam se ukládají stažená PDF a přílohy
IUCTO_MCP_MODE	ne	full	read-only nabídne jen 73 čtecích nástrojů, full všech 158
IUCTO_LOG_LEVEL	ne	info	debug / info / warn / error

Soubory

Nástroje pro PDF a přílohy soubor uloží na disk a vrátí cestu, ne jeho obsah: jedno faktura-PDF má stovky kilobajtů a zaplnilo by asistentovi kontext. Adresář nastavíte IUCTO_DOWNLOAD_DIR.

Při nahrávání přílohy pošlete buď file_path (cesta na stroji, kde běží server), nebo content_base64 spolu s filename. Povolené přípony a limit velikosti popisuje Nahrání přílohy.

Na co si dát pozor

Asistent píše do ostrého účetnictví

Klíč má stejná oprávnění jako uživatel ve webové aplikaci a sandbox neexistuje. Nástroje create*, update* a delete* píšou do skutečného účetnictví. Co založí createDocumentScan a createStockMovement, navíc z API nesmažete vůbec – uklidíte to jedině ručně ve webové aplikaci. Klíč nejde omezit na část účtu, platí pro celou firmu a MCP klient si ho ukládá do konfigurace jako čitelný text, takže s ním zacházejte jako s heslem. Na zkoušení si založte druhou, zkušební firmu.

Editace nahrazuje celý doklad

Nástroje update* posílají PUT, který nahradí celý záznam, ne jen pole, která jste poslali. Co v požadavku chybí, se v dokladu vyprázdní – i když to tam předtím bylo.

Asistent tohle sám od sebe nepozná. Když ho požádáte o změnu jediné položky, musí si nejdřív načíst současný stav dokladu (get*), doplnit do něj úpravu a poslat zpátky všechna pole. Ověřte si to v potvrzovacím dialogu: pokud požadavek obsahuje jen měněnou položku, zbytek dokladu po zápisu zmizí.

Týká se všech 22 nástrojů update* – faktur, opravných dokladů, objednávek, kontaktů, bankovních účtů, zakázek, středisek, skladových karet a dalších.

• Volání jdou do denní kvóty stejně jako přímá volání API, viz Limity a kvóty.
• Server je vhodný na práci s daty („vypiš mi neuhrazené faktury", „založ zákazníka"). Když píšete integraci, potřebujete popis rozhraní, na to je reference a OpenAPI specifikace.
• Seznam nástrojů zabere asistentovi kus kontextu hned na začátku sezení. Klienti, kteří umí načítat nástroje až podle potřeby, si ho zlevní sami.

Verze a změny

Server se vydává samostatně na npm, nezávisle na API. Úplný changelog je v balíčku a v repozitáři.

Verze	Datum	Co se změnilo
0.5.1	15. 9. 2026	oprava spouštění přes npx: 0.5.0 skončila chybou import: command not found
0.5.0	2. 9. 2026	ze 97 nástrojů 158: přibyly update* a delete* napříč API, k tomu account*, share*, email*, payProformaInvoiceIssued a createDocumentScan. Potvrzování editace a mazání, režim IUCTO_MCP_MODE.
0.3.0	26. 8. 2026	balík .mcpb pro Claude Desktop – instalace bez úpravy konfiguračního souboru
0.1.2	26. 8. 2026	nástroje se generují z OpenAPI popisu API, z 19 jich je 97. Balíček přejmenován na @iucto.cz/iucto-mcp-server a přesunut na veřejné npm. Názvy nástrojů odpovídají operationId, dřívější iucto_* skončily.

Aktualizace: klienti spouštění přes npx -y si nejnovější verzi stáhnou sami. Claude Desktop si drží nainstalovaný balík, takže tam je potřeba stáhnout a otevřít .mcpb znovu.

Zdrojový kód a hlášení chyb: github.com/iUcto/iucto-mcp-server.