Beancount.io LogoBeancount.io

Beancount MCP: Pripojte svoju účtovnú knihu ku Claude, Cursor a akémukoľvek AI asistentovi

9 minúty čítaniaMike ThriftMike Thrift
Beancount MCP: Pripojte svoju účtovnú knihu ku Claude, Cursor a akémukoľvek AI asistentovi

Web Beancount spúšťa MCP server — komunikujte so svojou účtovnou knihou zo Claude, Cursor a z akéhokoľvek AI nástroja, ktorý už používate

Vaše účtovné údaje sa stretávajú s vaším AI pracovným postupom. Žiadne kopírovanie a vkladanie. Žiadne exporty. Stačí sa opýtať.

Web Beancount dnes oznamuje Beancount MCP Server — koncový bod Model Context Protocol (MCP), ktorý vám umožňuje pripojiť vašu účtovnú knihu Beancount priamo ku Claude Desktop, Claude Code, Cursor, Windsurf alebo akémukoľvek inému AI klientovi kompatibilnému s MCP. Pokročilí používatelia sa po prvýkrát môžu pýtať účtovné otázky, spúšťať BQL dopyty a dokonca upravovať súbory účtovnej knihy priamo z AI nástrojov, v ktorých už žijú — bez prepínania záložiek alebo opustenia svojho pracovného postupu.

Súbory Beancount v čistom texte sú výkonné práve preto, že sú to len súbory. Ale odpoveď na otázku „koľko som minul na cestovanie minulý štvrťrok?" stále vyžaduje znalosť syntaxe BQL, znalosť toho, kde sú vaše súbory, a kopírovanie výsledkov do chatu. Server Beancount MCP toto trenie úplne odstraňuje.

So serverom Beancount MCP nakonfigurovaným vo vašom AI klientovi môžete:

  • Opýtať sa „Aké je dnes moje čisté imanie?" a získať živú odpoveď načerpanú z vašej skutočnej účtovnej knihy
  • Požiadať o zhrnutie výdavkov za minulý mesiac a nechať AI napísať BQL dopyt za vás
  • Povedať AI, aby pridala transakciu, a sledovať, ako potvrdí zmenu do git repozitára vašej účtovnej knihy
  • Prehliadať a čítať svoje súbory .beancount bez toho, aby ste kedy opustili svoj editor

Server je viazaný na účtovnú knihu: každá MCP relácia je autorizovaná presne pre jednu účtovnú knihu pomocou OAuth 2.1. Klienti ako Claude Code objavia a dokončia autorizačný tok automaticky — nie je potrebná žiadna manuálna správa tokenov. Vaša účtovná kniha zostáva tam, kde už žije, na backende Web Beancount: AI klient posiela štruktúrované volania nástrojov na náš server, ktorý číta alebo upravuje vašu účtovnú knihu vo vašom mene a vracia výsledky. Samotný MCP server neukladá nič nad rámec toho, čo obsahuje konverzácia vášho AI klienta.

Server Beancount MCP je dostupný odteraz pre všetkých používateľov Web Beancount.

Začíname

Server Beancount MCP je dostupný. Pridajte ho do svojho AI klienta za menej než minútu.

URL MCP servera

https://beancount.io/api-gateway/mcp

Claude Code (odporúčané — plný tok OAuth 2.1, nie je potrebný žiadny token)

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

Pri prvom použití Claude Code otvorí okno prehliadača. Výzva v prehliadači je miesto, kde vyberiete, ktorú účtovnú knihu pripojiť — schváľte raz a poverenia sa obnovujú automaticky. Máte viac než jednu účtovnú knihu? Pridajte server znova pod iným názvom (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) a autorizujte druhú účtovnú knihu v jej vlastnej výzve.

Claude Desktop / Cursor / Windsurf / Zed

Pridajte server do MCP konfigurácie svojho klienta (claude_desktop_config.json alebo ekvivalent). Klienti s podporou OAuth 2.1 otvoria pri prvom použití rovnakú výzvu v prehliadači — vyberte tam svoju účtovnú knihu:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

Ak váš klient zatiaľ nepodporuje tok OAuth, vygenerujte statický token (viazaný na jednu účtovnú knihu) z nastavení svojho účtu beancount.io a odovzdajte ho ako hlavičku:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Nemáte účet Web Beancount? Zaregistrujte sa na beancount.io — vaša účtovná kniha je vzdialená len jeden git push.

Často kladené otázky

Otázky zákazníkov

Čo je MCP a prečo je dôležitý pre Beancount?

MCP (Model Context Protocol) je otvorený štandard, ktorý umožňuje AI asistentom volať externé nástroje a zdroje údajov štruktúrovaným, bezpečným spôsobom. Predstavte si ho ako USB port pre AI: namiesto toho, aby AI hádala alebo vás žiadala o vloženie údajov, pripája sa priamo k vašim systémom. Pre používateľov Beancount to znamená, že váš AI klient dokáže dopytovať vaše skutočné údaje účtovnej knihy, čítať vaše skutočné súbory a robiť presné úpravy — nie hádať, čo by mohli obsahovať.

Ktorí AI klienti fungujú so serverom Beancount MCP?

Akýkoľvek klient kompatibilný s MCP, ktorý podporuje OAuth 2.1, funguje ihneď. Server Beancount MCP implementuje plný autorizačný tok OAuth 2.1 s PKCE, takže klienti ako Claude Code automaticky objavia autorizačný koncový bod servera a vyzvú vás na prihlásenie — nie je potrebné žiadne manuálne kopírovanie tokenov ani konfigurácia. Keď schválite prístup, klient ukladá a obnovuje poverenia automaticky.

Medzi klientov so známou podporou MCP + OAuth 2.1 patria Claude Code CLI, Claude Desktop, Cursor, Windsurf a Zed. Ako MCP ekosystém rastie, akýkoľvek nový klient, ktorý dodržiava špecifikáciu OAuth 2.1 MCP, bude fungovať bez zmien na našej strane.

Ako pripojím svoju účtovnú knihu?

Pre klientov, ktorí podporujú OAuth 2.1 (ako Claude Code):

  1. Pridajte URL servera Beancount MCP do MCP konfigurácie svojho klienta.
  2. Klient automaticky otvorí okno prehliadača na autorizáciu prístupu.
  3. Prihláste sa svojím účtom Web Beancount a vyberte účtovnú knihu, ku ktorej chcete udeliť prístup.
  4. Hotovo — klient odtiaľ spravuje ukladanie a obnovu tokenov.

Pre klientov bez podpory OAuth 2.1 vygenerujte statický token (viazaný na jednu účtovnú knihu) z nastavení svojho účtu Web Beancount a odovzdajte ho ako hlavičku Authorization: Bearer.

Je to to isté ako funkcia chatu „Ask AI" v paneli?

Zdieľajú rovnaké základné nástroje účtovnej knihy (BQL dopyty, čítanie/zápis súborov), ale MCP server je iný vstupný bod. Funkcia Ask AI v paneli je hostovaný zážitok chatu so sandboxom Claude Code postaveným na Cloudflare. MCP server je koncový bod protokolu, ku ktorému sa pripájate z vlastného AI klienta podľa vášho výberu — poskytuje vám väčšiu kontrolu, viac modelov a hlbšiu integráciu s vaším existujúcim pracovným postupom.

Čo môže AI so mojou účtovnou knihou skutočne robiť?

MCP server sprístupňuje štyri nástroje:

NástrojČo robí
runBqlQuerySpúšťa BQL (Beancount Query Language) na dopytovanie zostatkov, transakcií, účtov
listLedgerFilesPrehliada adresárovú štruktúru repozitára vašej účtovnej knihy
readLedgerFilesČíta obsah súborov .beancount a iných dokumentov účtovnej knihy
editLedgerFilesVytvára, aktualizuje, nahrádza alebo odstraňuje súbory v atomickom git commite

AI môže tieto nástroje kombinovať: objaviť štruktúru vašich súborov, prečítať relevantné súbory pre kontext, napísať BQL dopyt na zodpovedanie vašej otázky alebo navrhnúť a potvrdiť úpravu.

Môže AI upraviť moju účtovnú knihu bez toho, aby som o tom vedel?

Úpravy súborov vyžadujú, aby AI klient zavolal editLedgerFiles s popisom toho, čo mení. Dobre sa správajúci MCP klienti (vrátane Claude Code) vám to zobrazia pred vykonaním. Úpravy tiež podporujú režim dry_run, ktorý zobrazí náhľad presných zmien bez toho, aby čokoľvek zapísal, takže váš klient vám môže najprv ukázať diff. A každá potvrdená zmena je skutočný git commit v repozitári vašej účtovnej knihy, takže máte úplnú audítorskú stopu a čokoľvek môžete vrátiť späť pomocou štandardných git nástrojov.

Sú moje údaje odosielané tretej strane?

Údaje vašej účtovnej knihy prechádzajú cez backend Web Beancount (ktorý už spravuje vašu účtovnú knihu) a vracajú sa ako štruktúrované výsledky vášmu AI klientovi. AI model, ktorý používate (napríklad Claude), prijíma výsledky nástrojov ako akýkoľvek iný kontext. MCP server neukladá žiadne údaje nad rámec toho, čo už obsahuje konverzácia vášho AI klienta.

Každý token je viazaný na účtovnú knihu — čo to znamená?

Keď autorizujete MCP server, vyberiete, ku ktorej účtovnej knihe udeliť prístup. Táto relácia môže pristupovať iba k tejto účtovnej knihe. Ak máte viacero účtovných kníh, autorizujete samostatné relácie. To obmedzuje rozsah dosahu: relácia pre vašu osobnú účtovnú knihu sa nemôže dotknúť vašej firemnej účtovnej knihy.

Vyžaduje MCP server, aby bežalo webové UI Fava?

Nie. MCP server komunikuje s interným Fava API spravovaným infraštruktúrou Web Beancount (Fava je webové rozhranie, ktoré poháňa vašu účtovnú knihu beancount.io). Nemusíte mať otvorené ani prístupné UI Fava.

Čo sa stane, ak odvolám svoj MCP prístup?

Prebiehajúce MCP relácie dostanú pri ďalšom volaní nástroja chyby 401. Klienti, ktorí podporujú OAuth 2.1, sa automaticky pokúsia o opätovnú autorizáciu a vyzvú vás na opätovné prihlásenie.

Pod kapotou

Pre technicky zvedavých — ako je server postavený.

Prečo MCP namiesto budovania vlastného API/pluginu pre každý AI nástroj?

MCP je vznikajúci štandard a už ho podporujú všetky hlavné AI editory. Vybudovanie jedného kompatibilného MCP servera nám dáva kompatibilitu s celým ekosystémom naraz, oproti udržiavaniu samostatných integrácií pre Claude, Cursor, Windsurf a čokoľvek, čo sa objaví budúci štvrťrok. Protokol sa stará o objavovanie, schémy nástrojov a streaming — my sa sústredíme na doménovú logiku.

Prečo OAuth 2.1 namiesto statických API kľúčov?

OAuth 2.1 s PKCE je to, čo špecifikácia MCP odporúča pre vzdialené servery, a je to to, čo klienti ako Claude Code implementujú natívne. Praktický prínos: používatelia sa nikdy nedotknú tokenu. Klient objaví autorizačný server cez náš koncový bod metadát .well-known/oauth-protected-resource, dokončí PKCE a spravuje obnovu automaticky. Statické tokeny zostávajú podporované ako záložné riešenie pre klientov, ktorí ešte neimplementovali plný tok.

Prečo Streamable HTTP namiesto transportu SSE alebo stdio?

Streamable HTTP je MCP transport navrhnutý pre vzdialené servery cez HTTPS. Stdio je pre lokálne procesy. SSE (starší MCP transport) sa vyraďuje v prospech Streamable HTTP. Naši používatelia sa pripájajú z AI klientov, ktorí nie sú umiestnení spolu s naším serverom, takže Streamable HTTP je správna voľba orientovaná na budúcnosť.

Prečo je MCP relácia bezstavová (žiadny sessionIdGenerator)?

Nastavujeme sessionIdGenerator: undefined, aby bola každá požiadavka úplne bezstavová — medzi volaniami nástrojov sa nealokuje ani neuchováva žiadny stav relácie na strane servera. To zodpovedá bezstavovému režimu špecifikácie Streamable HTTP a udržiava server horizontálne škálovateľný bez afinity relácie. Kontext nástroja (identita účtovnej knihy, klient Fava API) sa rekonštruuje pri každej požiadavke z overeného OIDC tokenu.

Ako funguje overovanie prístupu k účtovnej knihe?

Po validácii OIDC tokenu resolveLedgerAccess overí cez Fava API, že overený používateľ má skutočne prístup k požadovanej účtovnej knihe. To zabraňuje tomu, aby sa platný token pre jednu účtovnú knihu použil na skúmanie účtovnej knihy iného používateľa (hĺbková ochrana nad rámec podpísaného tokenu).

Kam editLedgerFiles potvrdzuje zmeny?

Volá changeLedgerFiles na Fava API, ktoré vytvorí git commit v Gitea repozitári účtovnej knihy so správou AI edit: <description>. Popis pochádza z poľa description, ktoré AI vyplní — zobrazeného používateľovi v dobre sa správajúcich MCP klientoch pred vykonaním.

Čo je možnosť dry_run v editLedgerFiles?

dry_run: true overí všetky súborové operácie (skontroluje, či súbory existujú, overí, že staré reťazce str_replace sa zhodujú presne raz) a vráti náhľad toho, čo by sa potvrdilo — bez skutočného zápisu do git. To je užitočné pre AI klientov, ktorí chcú používateľovi zobraziť diff pred potvrdením.

Aký je povrch chýb viditeľný pre AI klientov?

Chyby nástrojov sa vracajú ako { isError: true, content: [{ type: "text", text: "..." }] } — štruktúrovaný formát chýb MCP SDK. AI klient prijíma chybovú správu ako text a môže rozhodnúť, ako ju spracovať (opakovať, nahlásiť používateľovi atď.). Chyby autentifikácie na úrovni HTTP (401) obsahujú hlavičku WWW-Authenticate odkazujúcu na metadáta chráneného zdroja OAuth, takže kompatibilní klienti môžu automaticky opätovne iniciovať autorizačný tok.

Späť na všetky príspevky