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/mcpClaude 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 обращается к внутреннему API Fava, которым управляет инфраструктура 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 и сохраняет горизонтальную масштабируемость сервера без привязки к сессии. Контекст инструмента (идентичность реестра, клиент API Fava) воссоздаётся для каждого запроса из проверенного OIDC-токена.
Как работает проверка доступа к реестру?
После проверки OIDC-токена resolveLedgerAccess проверяет через API Fava, что аутентифицированный пользователь действительно имеет доступ к запрошенному реестру. Это не позволяет использовать действительный токен для одного реестра, чтобы прощупать реестр другого пользователя (эшелонированная защита поверх подписанного токена).
Куда фиксирует editLedgerFiles?
Он вызывает changeLedgerFiles в API Fava, который создаёт 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, так что совместимые клиенты могут автоматически заново инициировать процесс авторизации.