# Beancount MCP: Подключите свой журнал к AI-ассистентам

Спросите своего AI-ассистента, сколько вы потратили в прошлом месяце, какие счета требуют сверки или куда отнести транзакцию. Beancount MCP предоставляет ему доступ к запросам, счетам и исходным файлам вашего размещенного журнала, поэтому он может работать с вашими книгами и показывать доказательства, стоящие за своим ответом.

![Глиняный ноутбук, подключенный к открытому зеленому журналу, с чеком в лотке для проверки и связанными блоками, представляющими историю Git.](/img/blog/beancount-mcp/hero.webp)

С разрешением на запись ассистент также может добавлять транзакции и обновлять файлы журнала. Вы можете попросить его предварительно просмотреть поддерживаемые правки, проверить предложенные записи и проверить журнал после изменения.

MCP означает Model Context Protocol — стандарт для подключения AI-приложений к внешним инструментам и данным. Это подключение работает с журналами, размещенными на **Beancount.io**. Ответы вашего ассистента отражают транзакции и цены, записанные там; подключение MCP не делает эти записи автоматически актуальными.

## Подключите свой AI-клиент

Используйте клиент, поддерживающий удаленный MCP через **Streamable HTTP**. URL сервера:

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

### Claude Code

Добавьте сервер из своего терминала:

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

Откройте Claude Code, выполните `/mcp`, выберите `beancount` и следуйте его процедуре аутентификации. Войдите в Beancount.io и проверьте запрашиваемые разрешения. Вернитесь к `/mcp`, чтобы подтвердить подключение. См. [инструкции по MCP для Claude Code](https://code.claude.com/docs/en/mcp) для деталей, специфичных для клиента.

Страница согласия позволяет ограничить доступ **одним журналом** или явно выбрать **Все доступные журналы**. Ограничение одним журналом — полезная отправная точка. При более широком доступе укажите ассистенту, какой журнал использовать, например `alice/personal`; инструменты журнала должны указывать свою цель при каждом вызове.

### Claude Desktop и Claude в вебе

Откройте **Customize → Connectors**, выберите **Add custom connector**, введите URL сервера и подключите свою учетную запись Beancount.io. Включите коннектор для разговора, где хотите его использовать. Для организационных учетных записей владельцу может потребоваться сначала добавить коннектор. Следуйте [руководству по удаленным коннекторам Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Добавьте сервер в свой личный `~/.cursor/mcp.json`:

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

Завершите вход через OAuth, когда Cursor запросит его, затем проверьте, что инструменты сервера доступны. [Документация Cursor по MCP](https://cursor.com/docs/mcp) охватывает настройку конфигурации и одобрения инструментов.

### Личные API-ключи

Для клиента, принимающего bearer-учетные данные, вы можете создать личный API-ключ в [Settings → Personal access tokens](https://beancount.io/settings/api-keys). **Создание ключа требует платного плана 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 файла, и дождись моего подтверждения.

Если эти счета уже открыты, предлагаемая запись будет выглядеть так:

```beancount
2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

Используйте имена счетов из своего журнала, затем завершите проверку:

1. Проверьте дату, сумму, счета и целевой файл в предварительном просмотре.
2. Подтвердите точное изменение, которое вы хотите, чтобы ассистент применил.
3. Попросите его выполнить `checkLedger` и сообщить о результирующем коммите и любых ошибках.

`appendLedgerText` по умолчанию отклоняет новые ошибки валидации. Общие изменения файлов используют `createLedgerFiles`, `updateLedgerFiles` и `deleteLedgerFiles`, каждый из которых фиксирует свои файлы в одном 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-клиента, с его настройками разговора, модели и одобрения.

**Почему я вижу инструмент, но не могу его использовать?**

Каталог инструментов включает операции, которые ваши учетные данные могут не разрешать. Проверьте ошибку и предоставленные разрешения. Неограниченные учетные данные также требуют явной цели журнала для инструментов журнала.

Подключите свой журнал и начните с одного вопроса, который вы можете проверить по своим книгам. Сохраняйте запрос вместе с ответом, затем добавляйте разрешения на запись, когда захотите получить помощь в ведении самого журнала.
