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, тож сумісні клієнти можуть автоматично повторно ініціювати процес авторизації.