Beancount MCP: Pripojte svoju knihu k AI asistentom

Opýtajte sa svojho AI asistenta, koľko ste minuli minulý mesiac, ktoré účty potrebujú reconciliáciu, alebo kam patrí transakcia. Beancount MCP mu dáva prístup k dotazom, účtom a zdrojovým súborom vašej hostovanej knihy, takže môže pracovať z vašich záznamov a ukázať dôkazy za svojou odpoveďou.

S oprávnením na zápis môže asistent tiež pridávať transakcie a aktualizovať súbory knihy. Môžete ho požiadať, aby zobrazil náhľad podporovaných úprav, skontroloval navrhované položky a po zmene skontroloval knihu.

MCP znamená Model Context Protocol: štandard pre pripojenie AI aplikácií k externým nástrojom a dátam. Toto pripojenie funguje s knihami hostovanými na Beancount.io. Odpovede vášho asistenta odrážajú transakcie a ceny zaznamenané tam; pripojenie MCP automaticky nezabezpečí, že tieto záznamy sú aktuálne.

Pripojte svoj AI klient​

Použite klienta, ktorý podporuje vzdialené MCP cez Streamable HTTP. URL servera je:

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

Claude Code​

Pridajte server z terminálu:

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

Otvorte Claude Code, spustite /mcp, vyberte beancount a postupujte podľa jeho autentifikačného toku. Prihláste sa do Beancount.io a skontrolujte požadované oprávnenia. Vráťte sa na /mcp a potvrďte pripojenie. Pozrite si inštrukcie pre MCP v Claude Code pre podrobnosti špecifické pre klienta.

Stránka so súhlasom vám umožňuje obmedziť prístup na jednu knihu alebo explicitne zvoliť Všetky prístupné knihy. Obmedzenie na jednu knihu je užitočným východiskovým bodom. Pri širšom prístupe povedzte asistentovi, ktorú knihu má použiť, napríklad alice/personal; nástroje pre knihy musia identifikovať svoj cieľ pri každom volaní.

Claude Desktop a Claude na webe​

Otvorte Prispôsobiť → Konektory, zvoľte Pridať vlastný konektor, zadajte URL servera a pripojte svoj Beancount.io účet. Povoľte konektor pre konverzáciu, v ktorej ho chcete použiť. Organizačné účty môžu vyžadovať, aby vlastník najprv pridal konektor. Postupujte podľa sprievodcu vzdialenými konektormi od Claude.

Cursor​

Pridajte server do svojho osobného ~/.cursor/mcp.json:

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

Dokončite OAuth prihlásenie, keď o to Cursor požiada, a potom skontrolujte, či sú nástroje servera dostupné. Dokumentácia MCP pre Cursor pokrýva konfiguráciu a nastavenia schvaľovania nástrojov.

Osobné API kľúče​

Pre klienta, ktorý prijíma poverenia typu bearer, si môžete vytvoriť osobný API kľúč v Nastavenia → Osobné prístupové tokeny. Vytvorenie kľúča vyžaduje platený Beancount.io plán. Vyberte ledger.read pre dotazy, voliteľne obmedzte kľúč na jednu knihu a skopírujte ho, keď sa zobrazí. Nakonfigurujte hlavičku autorizácie svojho klienta ako Authorization: Bearer YOUR_KEY pomocou jeho nastavení pre súkromné poverenia.

Uchovávajte kľúč mimo zdieľanej konfigurácie projektu. OAuth klienti spravujú poverenia cez svoj prihlasovací tok; pre túto cestu nemusíte vytvárať osobný kľúč.

Začnite otázkou o výdavkoch​

Vyskúšajte to po pripojení, pričom nahraďte názov knihy vaším:

Použi alice/personal. Identifikuj jej účty a meny, potom zhrň výdavky za august 2026 podľa účtov. Ukáž rozsah dátumov a BQL za každým súčtom, ponechaj meny oddelené a uveď všetky chyby validácie knihy. Nič nemeň.

Asistent môže zisťovať vaše knihy pomocou listLedgers, naučiť sa názvy vašich účtov cez getLedgerContext a spustiť runBqlQueryStructured pre typované výsledky dotazov. checkLedger vracia chyby validácie, počty položiek a najnovší commit.

Užitočná odpoveď zahŕňa knihu, obdobie, meny, súčty a podporné dotazy. Pre otázku o čistom imaní tiež požiadajte o metódu oceňovania a dátumy použitých cien. Chýbajúce transakcie alebo zastarané ceny môžu zmeniť odpoveď, aj keď kniha prejde validáciou.

Pridajte transakciu s náhľadom​

Pre nové položky appendLedgerText akceptuje bežný Beancount text a smeruje direktívy do súborov podľa konfigurácie vašej knihy. Jeho voľba dry_run vracia diff a predpokladané chyby validácie pred vykonaním commitu.

Napríklad:

Priprav nákup kávy za 4,50 USD s dátumom 15. septembra 2026, zaplatený z Assets:Cash a zatriedený pod Expenses:Food. Najprv skontroluj, či tieto účty existujú, a hľadaj zodpovedajúcu transakciu. Použi appendLedgerText s dry_run: true, ukáž navrhovanú položku a diff súboru a počkaj na moje potvrdenie.

S týmito už otvorenými účtami by navrhovaná položka vyzerala takto:

2026-09-15 * "Cafe" "Káva"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD

Použite názvy účtov z vašej vlastnej knihy a potom dokončite kontrolu:

1. Skontrolujte dátum, sumu, účty a cieľový súbor v náhľade.
2. Potvrďte presnú zmenu, ktorú má asistent vykonať.
3. Požiadajte ho, aby spustil checkLedger a oznámil výsledný commit a prípadné chyby.

appendLedgerText štandardne odmieta nové chyby validácie. Všeobecné zmeny súborov používajú editLedgerFiles, ktorý môže vytvárať, nahrádzať, aktualizovať alebo mazať súbory v jednom Git commite. Jeho náhľad tiež uvádza diff a predpokladané chyby. Skontrolujte výsledok a po zápise spustite checkLedger: úspešný commit môže stále obsahovať účtovnícke chyby.

Použite pracovný postup pre opakované účtovníctvo​

Server tiež poskytuje znovupoužiteľné MCP výzvy. Klienti s podporou výziev ich sprístupňujú vo svojom výbere príkazov alebo výziev:

Tieto výzvy vedú asistenta cez postup. Nespúšťajú účtovnícku úlohu len preto, že ich vyberiete, a neudeľujú dodatočné oprávnenia.

Reconciliácia potrebuje výpis a konečný zostatok. Samotný čistý výsledok validácie nemôže potvrdiť, že každá transakcia bola zaznamenaná. Požiadajte asistenta, aby identifikoval všetko, čo nemohol overiť, a ponechajte tieto otázky viditeľné v správe.

Pre bankové importy najprv prepojte banku v Beancount.io. Čítanie podrobností o pripojení vyžaduje administratívny prístup; odosielanie pripravených transakcií vyžaduje oprávnenie na zápis a príslušný prístup k tomuto bankovému pripojeniu. Pred autorizáciou odoslania skontrolujte navrhované kategórie a duplicity.

Pochopte prístup a nakladanie s dátami​

Oprávnenia pripojenia určujú, čo môže asistent robiť:

Váš existujúci prístup ku každej knihe stále platí. Obmedzenie poverenia na jednu knihu bráni volaniam knihy zacieľovať na inú; neobmedzené poverenie môže vybrať medzi knihami, ku ktorým máte prístup. OAuth klient si vyberá, ktoré oprávnenia požiada, takže si pred schválením prečítajte obrazovku so súhlasom.

MCP server nezobrazuje dialóg na schválenie človekom. Nastavenia vášho klienta určujú, kedy sa pýta pred volaním nástroja, a náhľady sa musia vyžiadať explicitne. Dodané pracovné postupy zápisu inštruujú asistenta, aby počkal na potvrdenie. Poverenie obmedzené na ledger.read poskytuje vynútenú hranicu, keď chcete analýzu bez zápisov.

Výsledky nástrojov, vrátane dotazovaných transakcií a súborov, ktoré asistent číta, vstupujú do kontextu vášho AI klienta a môžu byť spracované poskytovateľom jeho modelu. Beancount.io uchováva vašu knihu, Git históriu a prevádzkové záznamy. Bezstavové MCP pripojenie nie je sľubom, že sa žiadne dáta neuchovávajú; platia aj politiky dát vášho klienta a poskytovateľa.

Odvolané osobné API kľúče sú odmietnuté pri následných žiadostiach. OAuth prístupové tokeny zvyčajne trvajú jednu hodinu; odvolanie obnovovacieho tokenu okamžite nezneplatní už vydaný prístupový token. Prístup ku knihe sa znova kontroluje, keď sa spúšťajú chránené operácie.

Časté otázky​

Otvorí to knihu na mojom notebooku?

Hostovaný koncový bod pracuje s vašou Beancount.io knihou. Neotvára lokálny .bean súbor a nemusíte mať otvorenú kartu prehliadača s Favou.

Aký je rozdiel od AI asistenta v dashboarde?

Dashboard poskytuje vlastné chatové rozhranie. MCP sprístupňuje možnosti knihy z externého AI klienta, s konverzáciou, modelom a nastaveniami schvaľovania tohto klienta.

Prečo vidím nástroj, ale nemôžem ho použiť?

Katalóg nástrojov zahŕňa operácie, ktoré vaše poverenie nemusí povoľovať. Skontrolujte chybu a udelené oprávnenia. Neobmedzené poverenie tiež potrebuje explicitný cieľ knihy pre nástroje knihy.

Pripojte svoju knihu a začnite jednou otázkou, ktorú môžete overiť proti svojim záznamom. Uchovávajte dotaz s odpoveďou a potom pridajte oprávnenia na zápis, keď chcete pomoc s údržbou samotnej knihy.