# Beancount MCP: Свържете Ledger-а си с AI асистенти

Попитайте вашия AI асистент колко сте похарчили миналия месец, кои сметки се нуждаят от съгласуване или къде принадлежи дадена транзакция. Beancount MCP му дава достъп до заявките, сметките и изходните файлове на вашия хостиран ledger, така че да може да работи с вашите книги и да покаже доказателствата зад отговора си.

![Глинен лаптоп, свързан с отворен зелен ledger, с касова бележка в тава за преглед и свързани блокове, представляващи Git история.](/img/blog/beancount-mcp/hero.webp)

С разрешение за запис, асистентът може също да добавя транзакции и да актуализира ledger файлове. Можете да го помолите да прегледа поддържани редакции, да провери предложените записи и да провери ledger-а след промяна.

MCP означава Model Context Protocol: стандарт за свързване на AI приложения с външни инструменти и данни. Тази връзка работи с ledger-и, хоствани на **Beancount.io**. Отговорите на вашия асистент отразяват транзакциите и цените, записани там; свързването на MCP не прави автоматично тези записи актуални.

## Свържете вашия AI клиент

Използвайте клиент, който поддържа отдалечен MCP през **Streamable HTTP**. URL адресът на сървъра е:

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

### Claude Code

Добавете сървъра от вашия терминал:

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

Отворете Claude Code, изпълнете `/mcp`, изберете `beancount` и следвайте неговия процес на удостоверяване. Влезте в Beancount.io и прегледайте заявените разрешения. Върнете се на `/mcp`, за да потвърдите връзката. Вижте [инструкциите за MCP на Claude Code](https://code.claude.com/docs/en/mcp) за специфични за клиента подробности.

Страницата за съгласие ви позволява да ограничите достъпа до **един ledger** или изрично да изберете **Всички достъпни ledger-и**. Ограничението до един ledger е полезна отправна точка. При по-широк достъп, кажете на асистента кой ledger да използва, например `alice/personal`; инструментите за ledger трябва да идентифицират целта си при всяко извикване.

### Claude Desktop и Claude в мрежата

Отворете **Персонализиране → Конектори**, изберете **Добавяне на персонализиран конектор**, въведете URL адреса на сървъра и свържете вашия Beancount.io акаунт. Активирайте конектора за разговора, където искате да го използвате. Организационните акаунти може да изискват собственикът първо да добави конектора. Следвайте [ръководството за отдалечени конектори на Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Добавете сървъра към вашия личен `~/.cursor/mcp.json`:

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

Завършете OAuth влизането, когато Cursor го поиска, след което проверете дали инструментите на сървъра са налични. [Документацията за MCP на Cursor](https://cursor.com/docs/mcp) покрива конфигурацията и настройките за одобрение на инструменти.

### Лични API ключове

За клиент, който приема bearer идентификационни данни, можете да създадете личен API ключ в [Настройки → Лични токени за достъп](https://beancount.io/settings/api-keys). **Създаването на ключ изисква платен Beancount.io план.** Изберете `ledger.read` за заявки, по желание ограничете ключа до един ledger и го копирайте, когато бъде показан. Конфигурирайте заглавката за оторизация на вашия клиент като `Authorization: Bearer YOUR_KEY`, като използвате неговите настройки за частни идентификационни данни.

Дръжте ключа извън споделената проектна конфигурация. OAuth клиентите управляват идентификационните данни чрез своя процес на влизане; не е необходимо да създавате личен ключ за този път.

## Започнете с въпрос за разходи

Опитайте това след свързване, като замените името на ledger-а с вашето:

> Използвай `alice/personal`. Идентифицирай неговите сметки и валути, след което обобщи разходите за август 2026 по сметки. Покажи диапазона от дати и BQL зад всяка сума, дръж валутите отделни и докладвай всички грешки при валидиране на ledger-а. Не променяй нищо.

Асистентът може да открие вашите ledger-и с `listLedgers`, да научи имената на вашите сметки чрез `getLedgerContext` и да изпълни `runBqlQueryStructured` за типизирани резултати от заявки. `checkLedger` връща грешки при валидиране, брой записи и последния комит.

Полезен отговор включва ledger-а, периода, валутите, сумите и поддържащите заявки. За въпрос за нетна стойност, също поискайте метода на оценка и датите на използваните цени. Липсващи транзакции или остарели цени могат да променят отговора, дори когато ledger-ът преминава валидиране.

## Добавете транзакция с преглед

За нови записи, `appendLedgerText` приема обикновен Beancount текст и насочва директиви към файлове, използвайки конфигурацията на вашия ledger. Неговата опция `dry_run` връща diff и прогнозирани грешки при валидиране преди комитване.

Например:

> Подготви покупка на кафе за 4.50 USD, датирана 15 септември 2026, платена от `Assets:Cash` и категоризирана под `Expenses:Food`. Провери дали тези сметки съществуват и първо потърси съвпадаща транзакция. Използвай `appendLedgerText` с `dry_run: true`, покажи предложения запис и файловия diff, и изчакай моето потвърждение.

С тези вече отворени сметки, предложеният запис би изглеждал така:

```beancount
2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

Използвайте имена на сметки от вашия собствен ledger, след което завършете прегледа:

1. Проверете датата, сумата, сметките и целевия файл в прегледа.
2. Потвърдете точната промяна, която искате асистентът да приложи.
3. Помолете го да изпълни `checkLedger` и да докладва получения комит и всички грешки.

`appendLedgerText` отхвърля нови грешки при валидиране по подразбиране. Общите промени на файлове използват `createLedgerFiles`, `updateLedgerFiles` и `deleteLedgerFiles`, като всеки записва своите файлове в един Git комит. Прегледът им също докладва diff и прогнозирани грешки. Проверете резултата и изпълнете `checkLedger` след запис: успешен комит може все пак да съдържа счетоводни грешки.

## Използвайте работен процес за повтарящо се счетоводство

Сървърът също предоставя многократно използваеми MCP подкани. Клиенти с поддръжка на подкани ги показват в своя команден или подканващ избор:

| Работен процес | С какво ви помага |
| --- | --- |
| `spending-report` | Отговаря на въпрос за разходи с поддържащ BQL и без записи в ledger-а. |
| `reconcile-account` | Сравнява една сметка с предоставено извлечение, класифицира разликите и предлага липсващи записи. |
| `close-month` | Преглежда активни сметки, балансови проверки, повтарящи се транзакции и неразрешени флагове. |
| `categorize-imports` | Преглежда поетапни банкови транзакции и предлага категории, използвайки съществуващи сметки. |

Тези подкани насочват асистента през процедура. Те не изпълняват счетоводна задача просто защото ги изберете и не предоставят допълнителни разрешения.

Съгласуването изисква извлечение и крайно салдо. Чист резултат от валидиране сам по себе си не може да установи, че всяка транзакция е записана. Помолете асистента да идентифицира всичко, което не може да провери, и оставете тези въпроси видими в доклада.

За банкови импорти, първо свържете банката в Beancount.io. Четенето на подробности за връзката изисква административен достъп; подаването на поетапни транзакции изисква разрешение за запис и подходящ достъп до тази банкова връзка. Прегледайте предложените категории и дубликати, преди да разрешите подаването.

## Разберете достъпа и обработката на данни

Разрешенията на връзката определят какво може да прави асистентът:

| Разрешение | Достъп |
| --- | --- |
| `ledger.read` | Запитване и четене на ledger данни. |
| `ledger.write` | Четене на данни и извършване на обикновени ledger промени. |
| `ledger.admin` | Четене, запис и извършване на административни операции, където е разрешено. |

Вашият съществуващ достъп до всеки ledger все още се прилага. Ограничаването на идентификационни данни до един ledger предотвратява насочването на ledger извиквания към друг; неограничени идентификационни данни могат да избират сред ledger-ите, до които имате достъп. OAuth клиентът избира кои разрешения да поиска, така че прочетете екрана за съгласие, преди да одобрите.

**MCP сървърът не показва диалог за човешко одобрение.** Настройките на вашия клиент определят кога той пита преди извикване на инструмент, а прегледите трябва да бъдат изрично поискани. Предоставените работни процеси за запис инструктират асистента да изчака потвърждение. Идентификационни данни, ограничени до `ledger.read`, предоставят наложена граница, когато искате анализ без записи.

Резултатите от инструменти, включително запитани транзакции и файлове, които асистентът чете, влизат в контекста на вашия AI клиент и могат да бъдат обработени от неговия доставчик на модел. Beancount.io запазва вашия ledger, Git история и оперативни записи. Статусна MCP връзка не е обещание, че не се запазват данни; политиките за данни на вашия клиент и доставчик също се прилагат.

Отменените лични API ключове се отхвърлят при последващи заявки. OAuth токените за достъп обикновено издържат един час; отмяната на токен за опресняване не анулира незабавно вече издаден токен за достъп. Достъпът до ledger се проверява отново, когато се изпълняват защитени операции.

## Често задавани въпроси

**Отваря ли това ledger-а на моя лаптоп?**

Хостираният крайна точка работи върху вашия Beancount.io ledger. Той не отваря локален `.bean` файл и не е необходимо да имате отворен раздел на Fava в браузъра.

**Как се различава това от AI асистента в таблото?**

Таблото предоставя свой собствен чат интерфейс. MCP прави ledger възможностите достъпни от външен AI клиент, с неговите настройки за разговор, модел и одобрение.

**Защо мога да видя инструмент, но не мога да го използвам?**

Каталогът с инструменти включва операции, които вашите идентификационни данни може да не позволяват. Проверете грешката и предоставените разрешения. Неограничени идентификационни данни също изискват изрична ledger цел за ledger инструменти.

Свържете вашия ledger и започнете с един въпрос, който можете да проверите срещу вашите книги. Запазете заявката с отговора, след което добавете разрешения за запис, когато искате помощ с поддържането на самия ledger.
