Beancount MCP: Свържете своята счетоводна книга с Claude, Cursor и всеки AI асистент

Web Beancount пуска MCP сървър — говорете със своята счетоводна книга от Claude, Cursor и всеки AI инструмент, който вече използвате

Вашите счетоводни данни срещат вашия AI работен процес. Без копиране и поставяне. Без експорти. Просто попитайте.

Днес Web Beancount представя сървъра Beancount MCP — крайна точка на Model Context Protocol (MCP), която ви позволява да свържете своята счетоводна книга на Beancount директно с Claude Desktop, Claude Code, Cursor, Windsurf или всеки друг съвместим с MCP AI клиент. За първи път напредналите потребители могат да задават счетоводни въпроси, да изпълняват BQL заявки и дори да редактират файловете на счетоводната книга от вътрешността на AI инструментите, в които вече живеят — без да превключват раздели или да напускат работния си процес.

Файловете на Beancount в обикновен текст са мощни именно защото са просто файлове. Но отговорът на въпроса „колко похарчих за пътувания миналото тримесечие?" все още изисква да знаете синтаксиса на BQL, да знаете къде са файловете ви и да копирате резултатите в чат. Сървърът Beancount MCP премахва това затруднение изцяло.

С конфигуриран сървър Beancount MCP във вашия AI клиент можете да:

Питате „Каква е нетната ми стойност днес?" и да получите жив отговор, извлечен от вашата действителна счетоводна книга
Поискате обобщение на разходите от миналия месец и AI да напише BQL заявката вместо вас
Кажете на AI да добави транзакция и да го гледате как подава промяната в git хранилището на вашата счетоводна книга
Разглеждате и четете своите .beancount файлове, без изобщо да напускате редактора си

Сървърът е с обхват до една счетоводна книга: всяка MCP сесия е оторизирана за точно една счетоводна книга чрез OAuth 2.1. Клиенти като Claude Code откриват и завършват потока за оторизация автоматично — не се изисква ръчно управление на токени. Вашата счетоводна книга остава там, където вече се намира, в бекенда на Web Beancount: AI клиентът изпраща структурирани извиквания на инструменти към нашия сървър, който чете или редактира вашата счетоводна книга от ваше име и връща резултатите. Самият MCP сървър не съхранява нищо извън това, което съдържа собственият разговор на вашия AI клиент.

Сървърът Beancount MCP е достъпен от днес за всички потребители на Web Beancount.

Първи стъпки

Сървърът Beancount MCP е активен. Добавете го към вашия AI клиент за под минута.

URL на MCP сървъра

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

Claude Code (препоръчително — пълен OAuth 2.1 поток, без нужда от токен)

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

При първа употреба Claude Code ще отвори прозорец на браузъра. В подканата на браузъра вие избирате коя счетоводна книга да свържете — одобрете веднъж и идентификационните данни се обновяват автоматично. Имате повече от една счетоводна книга? Добавете сървъра отново под различно име (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) и оторизирайте другата счетоводна книга в нейната собствена подкана.

Claude Desktop / Cursor / Windsurf / Zed

Добавете сървъра към MCP конфигурацията на вашия клиент (claude_desktop_config.json или еквивалент). Клиентите с поддръжка на OAuth 2.1 отварят същата подкана на браузъра при първа употреба — изберете своята счетоводна книга там:

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

Ако вашият клиент все още не поддържа OAuth потока, генерирайте статичен токен (с обхват до една счетоводна книга) от настройките на акаунта си в beancount.io и го подайте като хедър:

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

Нямате акаунт в Web Beancount? Регистрирайте се на beancount.io — вашата счетоводна книга е на един git push разстояние.

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

Въпроси от клиенти

Какво е MCP и защо е важно за Beancount?

MCP (Model Context Protocol) е отворен стандарт, който позволява на AI асистентите да извикват външни инструменти и източници на данни по структуриран, безопасен начин. Мислете за него като за USB порт за AI: вместо AI да гадае или да ви моли да поставите данни, той се свързва директно с вашите системи. За потребителите на Beancount това означава, че вашият AI клиент може да прави справки в реалните данни на счетоводната ви книга, да чете действителните ви файлове и да прави прецизни редакции — а не да гадае какво може да съдържат.

Кои AI клиенти работят със сървъра Beancount MCP?

Всеки съвместим с MCP клиент, който поддържа OAuth 2.1, работи веднага. Сървърът Beancount MCP реализира пълния поток за оторизация OAuth 2.1 с PKCE, така че клиенти като Claude Code автоматично ще открият крайната точка за оторизация на сървъра и ще ви подканят да влезете — без ръчно копиране на токени или конфигурация. След като одобрите достъпа, клиентът съхранява и обновява идентификационните данни автоматично.

Клиентите с известна поддръжка на MCP + OAuth 2.1 включват Claude Code CLI, Claude Desktop, Cursor, Windsurf и Zed. С разрастването на MCP екосистемата всеки нов клиент, който следва спецификацията OAuth 2.1 MCP, ще работи без промени от наша страна.

Как да свържа своята счетоводна книга?

За клиенти, които поддържат OAuth 2.1 (като Claude Code):

Добавете URL на сървъра Beancount MCP към MCP конфигурацията на вашия клиент.
Клиентът автоматично отваря прозорец на браузъра, за да оторизира достъпа.
Влезте със своя акаунт в Web Beancount и изберете счетоводната книга, до която искате да предоставите достъп.
Готово — оттук нататък клиентът се грижи за съхранението и обновяването на токена.

За клиенти без поддръжка на OAuth 2.1 генерирайте статичен токен (с обхват до една счетоводна книга) от настройките на акаунта си в Web Beancount и го подайте като хедър Authorization: Bearer.

Това същото ли е като функцията за чат „Ask AI" в таблото?

Те споделят едни и същи основни инструменти за счетоводната книга (BQL заявки, четене/запис на файлове), но MCP сървърът е различна входна точка. Функцията Ask AI в таблото е хостнато чат изживяване с пясъчна среда на Claude Code, поддържана от Cloudflare. MCP сървърът е крайна точка на протокол, към която се свързвате от избран от вас AI клиент — давайки ви повече контрол, повече модели и по-дълбока интеграция със съществуващия ви работен процес.

Какво всъщност може да прави AI с моята счетоводна книга?

MCP сървърът предоставя четири инструмента:

Инструмент	Какво прави
`runBqlQuery`	Изпълнява BQL (Beancount Query Language), за да прави справки за салда, транзакции, сметки
`listLedgerFiles`	Разглежда структурата на директориите на хранилището на счетоводната ви книга
`readLedgerFiles`	Чете съдържанието на `.beancount` файлове и други документи на счетоводната книга
`editLedgerFiles`	Създава, обновява, замества или изтрива файлове в атомарен git комит

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

Може ли AI да променя счетоводната ми книга без мое знание?

Редакциите на файлове изискват AI клиентът да извика editLedgerFiles с описание на това, което променя. Добре поведените MCP клиенти (включително Claude Code) ви показват това преди изпълнение. Редакциите поддържат също режим dry_run, който визуализира точните промени, без да записва нищо, така че вашият клиент може първо да ви покаже diff. И всяка подадена промяна е реален git комит в хранилището на вашата счетоводна книга, така че имате пълна одитна следа и можете да отмените всичко със стандартни git инструменти.

Изпращат ли се данните ми на трета страна?

Данните на счетоводната ви книга преминават през бекенда на Web Beancount (който вече управлява счетоводната ви книга) и се връщат като структурирани резултати към вашия AI клиент. AI моделът, който използвате (например Claude), получава резултатите от инструментите като всеки друг контекст. MCP сървърът не съхранява никакви данни извън това, което разговорът на вашия AI клиент вече съдържа.

Всеки токен е с обхват до една счетоводна книга — какво означава това?

Когато оторизирате MCP сървъра, вие избирате до коя счетоводна книга да предоставите достъп. Тази сесия има достъп само до тази счетоводна книга. Ако имате няколко счетоводни книги, оторизирате отделни сесии. Това ограничава радиуса на въздействие: сесия за личната ви счетоводна книга не може да достигне бизнес счетоводната ви книга.

Изисква ли MCP сървърът уеб интерфейсът на Fava да работи?

Не. MCP сървърът комуникира с вътрешния Fava API, управляван от инфраструктурата на Web Beancount (Fava е уеб интерфейсът, който захранва вашата счетоводна книга в beancount.io). Не е необходимо да имате отворен или достъпен интерфейс на Fava.

Какво се случва, ако отменя достъпа си до MCP?

Текущите MCP сесии ще получат грешки 401 при следващото извикване на инструмент. Клиентите, които поддържат OAuth 2.1, автоматично ще опитат повторна оторизация, като ви подканят да влезете отново.

Под капака

За технически любопитните — как е изграден сървърът.

Защо MCP, а не изграждане на собствен API/плъгин за всеки AI инструмент?

MCP е нововъзникващият стандарт и вече се поддържа от всички основни AI редактори. Изграждането на един съвместим MCP сървър ни дава съвместимост с цялата екосистема наведнъж, вместо да поддържаме отделни интеграции за Claude, Cursor, Windsurf и каквото и да излезе следващото тримесечие. Протоколът се грижи за откриването, схемите на инструментите и стрийминга — ние се фокусираме върху логиката на домейна.

Защо OAuth 2.1 вместо статични API ключове?

OAuth 2.1 с PKCE е това, което спецификацията на MCP препоръчва за отдалечени сървъри, и това е, което клиенти като Claude Code реализират нативно. Практическата полза: потребителите никога не докосват токен. Клиентът открива сървъра за оторизация чрез нашата крайна точка за метаданни .well-known/oauth-protected-resource, завършва PKCE и управлява обновяването автоматично. Статичните токени остават поддържани като резервен вариант за клиенти, които не са реализирали пълния поток.

Защо Streamable HTTP вместо SSE или stdio транспорт?

Streamable HTTP е MCP транспортът, проектиран за отдалечени сървъри през HTTPS. Stdio е за локални процеси. SSE (по-старият MCP транспорт) е в процес на извеждане от употреба в полза на Streamable HTTP. Нашите потребители се свързват от AI клиенти, които не са разположени заедно с нашия сървър, така че Streamable HTTP е правилният и ориентиран към бъдещето избор.

Защо MCP сесията е без състояние (без sessionIdGenerator)?

Задаваме sessionIdGenerator: undefined, за да направим всяка заявка напълно без състояние — не се заделя или запазва състояние на сесия от страна на сървъра между извикванията на инструменти. Това съответства на режима без състояние от спецификацията на Streamable HTTP и поддържа сървъра хоризонтално мащабируем без обвързване към сесия. Контекстът на инструмента (идентичност на счетоводната книга, Fava API клиент) се възстановява за всяка заявка от валидирания OIDC токен.

Как работи проверката на достъпа до счетоводната книга?

След валидирането на OIDC токена, resolveLedgerAccess проверява чрез Fava API, че удостовереният потребител действително има достъп до заявената счетоводна книга. Това предотвратява използването на валиден токен за една счетоводна книга за сондиране на счетоводната книга на друг потребител (защита в дълбочина върху подписания токен).

Къде подава editLedgerFiles?

Той извиква changeLedgerFiles през Fava API, който създава git комит в Gitea хранилището на счетоводната книга със съобщението AI edit: <description>. Описанието идва от полето description, което AI попълва — показвано на потребителя в добре поведените MCP клиенти преди изпълнение.

Какво представлява опцията dry_run на editLedgerFiles?

dry_run: true валидира всички файлови операции (проверява дали файловете съществуват, потвърждава, че старите низове на str_replace съвпадат точно веднъж) и връща визуализация на това, което би било подадено — без реално записване в git. Това е полезно за AI клиенти, които искат да покажат diff на потребителя преди подаване.

Каква е повърхността на грешките, видима за AI клиентите?

Грешките на инструментите се връщат като { isError: true, content: [{ type: "text", text: "..." }] } — структурираният формат за грешки на MCP SDK. AI клиентът получава съобщението за грешка като текст и може да реши как да го обработи (повторен опит, докладване на потребителя и т.н.). Неуспехите при удостоверяване на HTTP ниво (401) включват хедър WWW-Authenticate, сочещ към метаданните за защитения OAuth ресурс, така че съвместимите клиенти могат автоматично да инициират повторно потока за оторизация.