# 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.

![Hlinený laptop pripojený k otvorenej zelenej knihe, s účtenkou v kontrolnej podložke a prepojenými blokmi reprezentujúcimi Git históriu.](/img/blog/beancount-mcp/hero.webp)

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:

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

### Claude Code

Pridajte server z terminálu:

```bash
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](https://code.claude.com/docs/en/mcp) 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

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

```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](https://cursor.com/docs/mcp) 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](https://beancount.io/settings/api-keys). **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:

```beancount
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ú `createLedgerFiles`, `updateLedgerFiles` a `deleteLedgerFiles`, z ktorých každý zapíše svoje súbory v jednom Git commite. Ich 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:

| Pracovný postup | S čím vám pomáha |
| --- | --- |
| `spending-report` | Odpovedať na otázku o výdavkoch s podporným BQL a bez zápisov do knihy. |
| `reconcile-account` | Porovnať jeden účet s dodaným výpisom, klasifikovať rozdiely a navrhnúť chýbajúce položky. |
| `close-month` | Skontrolovať aktívne účty, bilančné asercie, opakujúce sa transakcie a nevyriešené príznaky. |
| `categorize-imports` | Skontrolovať pripravené bankové transakcie a navrhnúť kategórie pomocou existujúcich účtov. |

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ť:

| Oprávnenie | Prístup |
| --- | --- |
| `ledger.read` | Dotazovať a čítať dáta knihy. |
| `ledger.write` | Čítať dáta a vykonávať bežné zmeny knihy. |
| `ledger.admin` | Čítať, zapisovať a vykonávať administratívne operácie tam, kde je to autorizované. |

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.
