Ako som si postavil MCP server, aby mi AI asistent posielal faktúry

Vediem malú analytickú konzultačnú firmu. To znamená, že robím dve veci: samotné konzultácie a všetko ostatné – fakturáciu, sledovanie platieb, naháňanie faktúr po splatnosti, administratívu okolo účtovníctva. Tú druhú časť nemá nikto rád.

Claude Code používam denne ako hlavný nástroj na vývoj a v istej chvíli mi napadlo: čo keby môj AI asistent zvládol aj fakturáciu? Nie cez nejakú hotovú integráciu, ale tak, že by komunikoval priamo s mojím účtovným systémom?

Tak som si ho postavil. Vlastný MCP server, ktorý prepája Claude Code s iDokladom, českou fakturačnou platformou, ktorú používam. Teraz stačí povedať „vyfakturuj klientovi X 40 hodín po 120 €“ a je to.

Čo je MCP?

Model Context Protocol je otvorený štandard, ktorý umožňuje AI modelom pracovať s externými nástrojmi a zdrojmi dát. Predstav si ho ako USB port pre AI – štandardizovaný spôsob, ako pripojiť nové schopnosti.

Claude Code podporuje MCP natívne. Zadefinuješ server, sprístupníš v ňom nejaké nástroje a Claude ich môže počas konverzácie volať. Žiadne API wrappery, žiadne triky s prompt engineeringom. Model vidí tvoje nástroje ako plnohodnotné funkcie, ktoré môže zavolať.

Kľúčové je toto: MCP servery sú len programy, ktoré cez stdin/stdout komunikujú konkrétnym protokolom. Napísať ich môžeš v Pythone, TypeScripte alebo v čomkoľvek inom. Bežia lokálne na tvojom počítači, takže tvoje dáta ho nikdy neopustia (okrem samotných API volaní na službu, ktorú integruješ).

Prečo iDoklad?

iDoklad je populárna fakturačná platforma v Česku a na Slovensku. Má solídne REST API (v3), správne rieši DPH pri európskej fakturácii a generuje poriadne PDF faktúry. Používam ho už roky.

Problém: každý mesiac som otvoril webové rozhranie, ručne vytvoril faktúry, rozposlal ich a potom priebežne kontroloval, ktoré sú už zaplatené. Nie je to ťažká práca, ale presne ten typ opakovanej administratívy, ktorá ti po kúskoch ukrajuje z dňa.

S MCP serverom môžem zostať v termináli a mechanickú prácu nechať na Clauda.

Čo to vie

Server sprístupňuje 15 nástrojov v štyroch kategóriách:

Fakturácia – Vytvorenie faktúr, ich výpis s filtrami, detail, stiahnutie PDF a odoslanie e-mailom. Pri vytváraní sa najprv stiahne predvolená šablóna z iDokladu a až potom sa do nej doplnia tvoje údaje, takže výsledok zodpovedá štýlu tvojich doterajších faktúr.

Kontakty – Vyhľadávanie klientov, zobrazenie detailu, pridanie nových. Keď pribudne nový klient, jednoducho Claudovi poviem názov firmy, IČO a adresu.

Platby – Prehľad o tom, čo je zaplatené, označenie faktúr ako uhradených a výpis všetkých nezaplatených faktúr a faktúr po splatnosti. Toto používam najviac. „Čo je nezaplatené?“ je asi otázka, ktorú píšem najčastejšie.

Analytika – Tržby podľa klientov, tržby podľa mesiacov, súhrny faktúr, top klienti podľa celkovej fakturácie. Hodí sa na štvrťročné vyhodnotenie alebo keď len chcem vedieť, ako ide tento rok.

Ako to funguje

Architektúra je jednoduchá. Python, asynchrónne HTTP cez httpx a oficiálne MCP Python SDK.

server.py          → MCP vstupný bod (stdio transport)
├── config.py      → Konfigurácia cez environment premenné
├── auth.py        → OAuth2 životný cyklus tokenov
├── client.py      → HTTP wrapper pre iDoklad API
└── tools/
    ├── invoices.py
    ├── contacts.py
    ├── payments.py
    └── statistics.py

Každý modul s nástrojmi má rovnakú štruktúru: funkciu get_tools(), ktorá deklaruje, čo je k dispozícii, a funkciu handle_tool(), ktorá to vykoná. Claude vidí popisy nástrojov a ich parametre, rozhodne sa, kedy ich zavolať, a o zvyšok sa postará server.

Autentifikácia

Toto bola najzložitejšia časť. iDoklad používa OAuth2 Authorization Code flow – ten, pri ktorom sa otvorí prehliadač, prihlásiš sa, udelíš povolenie a presmeruje ťa späť aj s tokenom.

Pre CLI nástroj je to nešikovné. Riešenie: samostatný príkaz idoklad-mcp-login, ktorý:

spustí dočasný lokálny server na porte 11470
otvorí ti v prehliadači autorizačnú stránku iDokladu
zachytí callback s autorizačným kódom
vymení ho za access a refresh token
uloží ich do ~/.idoklad-mcp/tokens.json

Toto spravíš raz. Potom server tokeny automaticky obnovuje ešte pred ich expiráciou (so 60-sekundovou rezervou). Ak vyprší aj samotný refresh token, jednoducho znova spustíš prihlasovací príkaz.

Vytvorenie faktúry

Tu to začína byť zaujímavé. Keď Claude zavolá create_issued_invoice, server:

stiahne z iDokladu predvolenú šablónu faktúry (aby nastavenia DPH, číslovanie a formátovanie sedeli s tvojím účtom)
doplní do nej ID partnera a zadané položky
pošle výsledok do API
vráti detail vytvorenej faktúry

Pre každú položku môžeš určiť sadzbu DPH (nulovú, zníženú alebo základnú 21 %) a o výpočty sa postará server. Bežná interakcia vyzerá takto:

„Vytvor faktúru pre ACME Corp – 40 hodín analytického poradenstva po 120 €/hod., základná DPH.“

Claude vyhľadá klienta, zavolá nástroj a faktúra je na svete. Potom stačí napísať „pošli ju“ a PDF odíde e-mailom.

Každodenné používanie

Takto dnes vyzerá bežný mesiac:

Koniec mesiaca: „Vytvor faktúry pre všetkých aktívnych klientov podľa hodín zaznamenaných za tento mesiac.“ Vložím hodiny, Claude vytvorí jednotlivé faktúry a rozpošle ich.

Kontrola v polovici mesiaca: „Ktoré faktúry sú ešte nezaplatené?“ Claude stiahne zoznam, ukáže mi, kto mešká, a ja sa rozhodnem, či pošlem upomienku.

Štvrťročné vyhodnotenie: „Ukáž mi tržby podľa klientov za Q4.“ Zobrazí sa tabuľka so súčtami. Žiadny spreadsheet, žiadny dashboard – len otázka a odpoveď.

Nový klient: „Pridaj ACME Corp do iDokladu – tu sú ich údaje.“ Kontakt je vytvorený a pripravený na fakturáciu.

Celý fakturačný workflow, pri ktorom som predtým musel prepnúť do webovej aplikácie, preklikať sa formulármi a ručne sledovať platby, sa teraz odohráva v tom istom termináli, v ktorom robím všetko ostatné.

Čo som sa pri tom naučil

MCP je jednoduchší, než sa zdá. Dokumentácia k protokolu môže pôsobiť hutne, ale postaviť server v podstate znamená: zadefinovať nástroje pomocou JSON schém, spracovať volania a vrátiť výsledky. Protokolovú vrstvu vyrieši Python SDK.

OAuth2 v CLI nástrojoch je otrava, ale dá sa to vyriešiť. Celé to presmerovávanie cez prehliadač pôsobí pri terminálovom nástroji ako hack, ale z pohľadu bezpečnosti je to správny prístup. Získaš riadnu autorizáciu a nemusíš nikde ukladať heslá.

Popisy nástrojov sú dôležitejšie, než si myslíš. Claude sa podľa popisov tvojich nástrojov rozhoduje, kedy a ako ich zavolať. Vágne popisy vedú k zlým volaniam. Ladením popisov som strávil viac času než písaním samotnej logiky.

Modulárne je lepšie ako monolitické. Rozdelenie nástrojov do samostatných súborov podľa domény (faktúry, kontakty, platby, štatistiky) vývoj výrazne zrýchlilo. Každý modul je nezávislý, dá sa testovať a ľahko rozšíriť.

Začni tým, čo naozaj používaš. Všetkých 15 nástrojov som nestaval naraz. Začal som nástrojom „zobraz nezaplatené faktúry“, lebo to som kontroloval najčastejšie. Potom pribudlo vytváranie, potom platby, potom analytika. Stavaj pre svoj reálny workflow, nie podľa zoznamu funkcií.

Čo ďalej

Momentálne je fakturácia poloautomatická. Poviem Claudovi, čo má vyfakturovať, a on sa postará o vytvorenie a odoslanie. Stále si však musím dohľadať hodiny a zistiť, čo patrí na ktorú faktúru. To je ďalší kus práce, ktorého sa chcem zbaviť.

Plán je prepojiť to s mojím systémom na správu úloh – GitHub Issues a Projects, kde už teraz sledujem všetku prácu pre klientov. Každá úloha má klienta, projekt a zaznamenaný čas. Na konci mesiaca by mal stačiť jeden prompt:

„Vyfakturuj január všetkým klientom.“

Claude by z GitHubu stiahol všetky dokončené úlohy a zaznamenané hodiny, zoskupil ich podľa klienta a projektu, vytvoril v iDoklade príslušné faktúry a rozposlal ich. Mesačná fakturácia jednou vetou namiesto celého popoludnia.

V tom je skutočný prísľub MCP – nejde len o prepojenie jedného nástroja, ale o reťazenie viacerých integrácií, aby AI zvládla celé workflowy od začiatku do konca.

Zdroje: