Спросите своего 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, чтобы подтвердить подключение. См. инструкции по MCP для Claude Code для деталей, специфичных для клиента.
Страница согласия позволяет ограничить доступ одним журналом или явно выбрать Все доступные журналы. Ограничение одним журналом — полезная отправная точка. При более широком доступе укажите ассистенту, какой журнал использовать, например alice/personal; инструменты журнала должны указывать свою цель при каждом вызове.
Claude Desktop и Claude в вебе
Откройте Customize → Connectors, выберите Add custom connector, введите URL сервера и подключите свою учетную запись Beancount.io. Включите коннектор для разговора, где хотите его использовать. Для организационных учетных записей владельцу может потребоваться сначала добавить коннектор. Следуйте руководству по удаленным коннекторам Claude.
Cursor
Добавьте сервер в свой личный ~/.cursor/mcp.json:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Завершите вход через OAuth, когда Cursor запросит его, затем проверьте, что инструменты сервера доступны. Документация Cursor по MCP охватывает настройку конфигурации и одобрения инструментов.
Личные API-ключи
Для клиента, принимающего bearer-учетные данные, вы можете создать личный API-ключ в Settings → Personal access tokens. Создание ключа требует платного плана 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" "Coffee"
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-токены доступа обычно действуют один час; отзыв refresh-токена не немедленно аннулирует уже выданный access-токен. Доступ к журналу проверяется снова, когда выполняются защищенные операции.
Частые вопросы
Открывает ли это журнал на моем ноутбуке?
Размещенная конечная точка работает с вашим журналом Beancount.io. Она не открывает локальный файл .bean, и вам не нужна открытая вкладка браузера Fava.
Чем это отличается от AI-ассистента на панели управления?
Панель управления предоставляет собственный интерфейс чата. MCP делает возможности журнала доступными из внешнего AI-клиента, с его настройками разговора, модели и одобрения.
Почему я вижу инструмент, но не могу его использовать?
Каталог инструментов включает операции, которые ваши учетные данные могут не разрешать. Проверьте ошибку и предоставленные разрешения. Неограниченные учетные данные также требуют явной цели журнала для инструментов журнала.
Подключите свой журнал и начните с одного вопроса, который вы можете проверить по своим книгам. Сохраняйте запрос вместе с ответом, затем добавляйте разрешения на запись, когда захотите получить помощь в ведении самого журнала.
