Запитайте свого AI-асистента, скільки ви витратили минулого місяця, які рахунки потребують звірки або куди віднести транзакцію. Beancount MCP надає йому доступ до запитів, рахунків і вихідних файлів вашого хостингового реєстру, тож він може працювати з вашими книгами та показувати докази, що стоять за його відповіддю.
З правом на запис асистент також може додавати транзакції та оновлювати файли реєстру. Ви можете попросити його показати попередній перегляд підтримуваних змін, переглянути запропоновані записи та перевірити реєстр після зміни.
MCP розшифровується як Model Context Protocol — це стандарт для підключення AI-застосунків до зовнішніх інструментів і даних. Це з'єднання працює з реєстрами, розміщеними на Beancount.io. Відповіді вашого асистента відображають транзакції та ціни, записані там; підключення MCP не робить ці записи актуальними автоматично.
Підключіть свій AI-клієнт
Використовуйте клієнт, який підтримує віддалений MCP через Streamable HTTP. URL-адреса сервера:
https://beancount.io/api-gateway/mcpClaude Code
Додайте сервер із терміналу:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpВідкрийте Claude Code, виконайте /mcp, виберіть beancount і пройдіть його процес автентифікації. Увійдіть у Beancount.io та перегляньте запитані дозволи. Поверніться до /mcp, щоб підтвердити з'єднання. Див. інструкції Claude Code щодо MCP для деталей, специфічних для клієнта.
Сторінка згоди дозволяє обмежити доступ до одного реєстру або явно обрати Усі доступні реєстри. Обмеження одним реєстром — корисна відправна точка. При ширшому доступі вкажіть асистенту, який реєстр використовувати, наприклад alice/personal; інструменти реєстру повинні визначати свою ціль у кожному виклику.
Claude Desktop і Claude в Інтернеті
Відкрийте Налаштувати → З'єднувачі, оберіть Додати власний з'єднувач, введіть URL-адресу сервера та підключіть свій обліковий запис Beancount.io. Увімкніть з'єднувач для розмови, де ви хочете його використовувати. Для організаційних облікових записів власник спершу може додати з'єднувач. Дотримуйтесь посібника Claude щодо віддалених з'єднувачів.
Cursor
Додайте сервер до свого особистого ~/.cursor/mcp.json:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Завершіть вхід через OAuth, коли Cursor його запитає, а потім перевірте, що інструменти сервера доступні. Документація Cursor щодо MCP охоплює налаштування та параметри схвалення інструментів.
Особисті API-ключі
Для клієнта, який приймає облікові дані bearer, ви можете створити особистий API-ключ у Налаштування → Персональні токени доступу. Створення ключа потребує платного плану Beancount.io. Оберіть ledger.read для запитів, за бажанням обмежте ключ одним реєстром і скопіюйте його, коли він з'явиться. Налаштуйте заголовок авторизації свого клієнта як Authorization: Bearer YOUR_KEY, використовуючи його приватні налаштування облікових даних.
Тримайте ключ подалі від спільної конфігурації проєкту. OAuth-клієнти керують обліковими даними через свій процес входу; вам не потрібно створювати особистий ключ для цього шляху.
Почніть із запитання про витрати
Спробуйте це після підключення, замінивши назву реєстру на свою:
Використовуй
alice/personal. Визнач його рахунки та валюти, потім підсумуй витрати за серпень 2026 року за рахунками. Покажи діапазон дат і BQL за кожною сумою, тримай валюти окремо та повідом про будь-які помилки валідації реєстру. Нічого не змінюй.
Асистент може виявити ваші реєстри за допомогою listLedgers, дізнатися назви ваших рахунків через getLedgerContext і виконати runBqlQueryStructured для типізованих результатів запитів. checkLedger повертає помилки валідації, кількість записів та останній коміт.
Корисна відповідь містить реєстр, період, валюти, підсумки та підтверджувальні запити. Для запитання про чисту вартість також попросіть метод оцінки та дати використаних цін. Відсутні транзакції або застарілі ціни можуть змінити відповідь, навіть якщо реєстр проходить валідацію.
Додайте транзакцію з попереднім переглядом
Для нових записів appendLedgerText приймає звичайний текст Beancount і спрямовує директиви у файли, використовуючи конфігурацію вашого реєстру. Його опція dry_run повертає diff і прогнозовані помилки валідації до коміту.
Наприклад:
Підготуй покупку кави на 4.50 USD від 15 вересня 2026 року, сплачену з
Assets:Cashі віднесену доExpenses:Food. Спершу перевір, чи існують ці рахунки, і пошукай схожу транзакцію. ВикористайappendLedgerTextзdry_run: true, покажи запропонований запис і diff файлу, і чекай на моє підтвердження.
Якщо ці рахунки вже відкриті, запропонований запис виглядав би так:
2026-09-15 * "Cafe" "Кава"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDВикористовуйте назви рахунків зі свого власного реєстру, а потім завершіть перегляд:
- Перевірте дату, суму, рахунки та цільовий файл у попередньому перегляді.
- Підтвердьте точну зміну, яку ви хочете, щоб асистент застосував.
- Попросіть його запустити
checkLedgerі повідомити про отриманий коміт та будь-які помилки.
appendLedgerText за замовчуванням відхиляє нові помилки валідації. Загальні зміни файлів використовують editLedgerFiles, який може створювати, замінювати, оновлювати або видаляти файли одним комітом Git. Його попередній перегляд також повідомляє про diff і прогнозовані помилки. Перевірте результат і запустіть checkLedger після запису: успішний коміт все ще може містити бухгалтерські помилки.
Використовуйте робочий процес для регулярного ведення книг
Сервер також надає багаторазові підказки MCP. Клієнти з підтримкою підказок показують їх у своєму виборі команд або підказок:
| Робочий процес | Що він допомагає робити |
|---|---|
spending-report | Відповісти на запитання про витрати з підтверджувальним BQL і без записів у реєстр. |
reconcile-account | Порівняти один рахунок із наданою випискою, класифікувати відмінності та запропонувати відсутні записи. |
close-month | Переглянути активні рахунки, балансові перевірки, повторювані транзакції та невирішені прапорці. |
categorize-imports | Переглянути поставлені банківські транзакції та запропонувати категорії, використовуючи існуючі рахунки. |
Ці підказки скеровують асистента через процедуру. Вони не запускають бухгалтерську задачу просто тому, що ви їх обираєте, і не надають додаткових дозволів.
Звірка потребує виписки та кінцевого балансу. Лише чистий результат валідації не може встановити, що кожна транзакція була записана. Попросіть асистента визначити все, що він не зміг перевірити, і залиште ці питання видимими у звіті.
Для банківських імпортів спершу зв'яжіть банк у Beancount.io. Читання деталей з'єднання потребує адміністративного доступу; подання поставлених транзакцій потребує права на запис і відповідного доступу до цього банківського з'єднання. Перегляньте запропоновані категорії та дублікати перед авторизацією подання.
Розуміння доступу та обробки даних
Дозволи з'єднання визначають, що може робити асистент:
| Дозвіл | Доступ |
|---|---|
ledger.read | Запитувати та читати дані реєстру. |
ledger.write | Читати дані та вносити звичайні зміни в реєстр. |
ledger.admin | Читати, записувати та виконувати адміністративні операції там, де авторизовано. |
Ваш наявний доступ до кожного реєстру все ще застосовується. Обмеження облікових даних одним реєстром запобігає націлюванню викликів реєстру на інший; необмежені облікові дані можуть обирати серед реєстрів, до яких ви маєте доступ. OAuth-клієнт вибирає, які дозволи запитувати, тому прочитайте екран згоди перед схваленням.
Сервер MCP не показує діалог схвалення людиною. Налаштування вашого клієнта визначають, коли він запитує перед викликом інструменту, і попередні перегляди потрібно запитувати явно. Надані робочі процеси запису інструктують асистента чекати підтвердження. Облікові дані, обмежені ledger.read, забезпечують примусову межу, коли ви хочете аналіз без записів.
Результати інструментів, включаючи запитувані транзакції та файли, які читає асистент, потрапляють у контекст вашого AI-клієнта та можуть оброблятися провайдером його моделі. Beancount.io зберігає ваш реєстр, історію Git та операційні записи. З'єднання MCP без збереження стану не є обіцянкою, що дані не зберігаються; політики даних вашого клієнта та провайдера також застосовуються.
Відкликані особисті API-ключі відхиляються на наступних запитах. Токени доступу OAuth зазвичай діють одну годину; відкликання токена оновлення не негайно анулює вже виданий токен доступу. Доступ до реєстру перевіряється знову, коли виконуються захищені операції.
Поширені запитання
Чи відкриває це реєстр на моєму ноутбуці?
Хостинговий кінцевий пункт працює з вашим реєстром Beancount.io. Він не відкриває локальний файл .bean, і вам не потрібно тримати відкриту вкладку браузера Fava.
Чим це відрізняється від AI-асистента в панелі керування?
Панель керування надає власний чат-інтерфейс. MCP робить можливості реєстру доступними із зовнішнього AI-клієнта, з його розмовою, моделлю та налаштуваннями схвалення.
Чому я бачу інструмент, але не можу ним користуватися?
Каталог інструментів включає операції, які ваші облікові дані можуть не дозволяти. Перевірте помилку та надані дозволи. Необмежені облікові дані також потребують явної цілі реєстру для інструментів реєстру.
Підключіть свій реєстр і почніть з одного запитання, яке ви можете перевірити за своїми книгами. Збережіть запит разом із відповіддю, а потім додайте права на запис, коли захочете допомоги у веденні самого реєстру.
