openbanking-mcp — читать свои счета и предупреждать ЗАРАНЕЕ

Репозиторий называется openbanking-mcp, команда называется bankread. Это не невнимательность: имя репозитория говорит о том, что это — MCP-сервер поверх Open Banking, потому что так его находят. Имя команды говорит о том, что с ним делают, и bankread doctor произносится лучше, чем openbanking-mcp doctor. Пути конфигурации (~/.config/bankread, связка ключей bankread-enablebanking) следуют за командой, а не за репозиторием.

Только чтение банковских счетов через DSP2 (лицензия AIS), плюс ежедневная сводка в Todoist. Python 3.11+, никаких сторонних зависимостей: urllib для HTTP, JSON-RPC написан вручную для MCP-сервера. Работает на Mac, а не в облаке.

⚠ Поставщика данных нужно выбрать — прочитайте перед началом

Этот репозиторий родился с клиентом GoCardless Bank Account Data (бывший Nordigen), который был очевидным бесплатным путём. Проверено 2026-08-20: этот сервис закрыт для новых регистраций и находится в процессе остановки. bankreadlib/gocardless.py поэтому полезен только тем, у кого уже был аккаунт.

Бесплатная замена для личного использования — Enable Banking, чей уровень Restricted Production даёт настоящие производственные данные только по тем счетам, которые вы подключаете сами — что именно и есть этот случай, и без лицензии. Клиент Enable Banking написан (bankreadlib/enablebanking.py): самостоятельная регистрация по email, аутентификация через JWT с подписью RS256 — без зависимостей, достаточно стандартной библиотеки (bankreadlib/rs256.py). Обзор практичных решений для BoursoBank и три открытия, изменившие код, — в docs/fournisseurs.md.

Остаётся одна вещь, которую никто не может сделать за вас: создать аккаунт Enable Banking, зарегистрировать там свои банковские счета и подписать согласие. Идентификатор приложения и приватный ключ являются личными — здесь нечего обобществлять, и именно с этого нужно начинать.

Всё остальное в репозитории не зависит от поставщика.

Проблема, которую он решает, и та, которую не решает

BoursoBank уже отправляет «ваш баланс низкий». Caisse d'Épargne уже отправляет «поступление денег». Amazon отправляет «в процессе доставки», Leboncoin — «продавец подтвердил». Информация уже приходит — просто слишком поздно и не туда.

• слишком поздно: предупреждение о пороге срабатывает ПОСЛЕ списания. Утром 15-го налоги уже прошли, счёт низкий, и предупреждение это констатирует;

• не туда: среди двухсот писем, большинство из которых не читаются.

Этот проект не ищет недостающую информацию. Он делает единственное, что никто не делает: вычитание. Сегодняшний баланс минус то, что спишется до конца месяца. Ни банк, ни налоговая не могут этого сделать — ни один из них не видит другого.

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

Related MCP server: bank.mcp

Только чтение, и не из вежливости

Подключение идёт через лицензию DSP2 / AIS поставщика (Enable Banking, бесплатный уровень Restricted Production). AIS — это агрегация информации о счетах. Инициация платежа — это отдельная лицензия (PIS), которой у этого токена нет и которую банк ему не откроет. Худший сценарий утечки — чтение истории, но никогда движение денег. Это единственная причина, по которой этот проект имеет право на существование.

Три практических следствия:

• учётные данные поставщика хранятся в связке ключей macOS, а не в файле — файл попадает в tar-архив резервной копии, в неудачный cat, в rsync на NAS. Для Enable Banking это включает приватный ключ RSA: bankread secrets --set читает его, сохраняет и напоминает удалить загруженный .pem;

• банковское согласие истекает — от трёх до шести месяцев в зависимости от того, что предоставляет банк, и сохраняется именно его ответ, а не наш запрос. Ничто не может продлить его за вас: нужно снова зайти на сайт своего банка. doctor предупреждает за 14 дней (не за 1 день, когда выходных хватило бы, чтобы всё аннулировать);

• всё это работает на Mac. Не в облачной сессии, не в контейнере.

Начало работы

Посмотреть, что это делает, сразу

./bankread demo

Вымышленный счёт, 400 дней сфабрикованной истории, воображаемый баланс — и настоящее обнаружение и настоящее прогнозирование, которые на этом работают. Ничего не записывается вне временной папки.

Что показывает демонстрация, и в чём вся суть:

    2026-08-23 ±3j    -890.00  →     394.55   Loyer …          [loyer]
    2026-08-25 ±3j    -412.00  →     -17.45   Dgfip Impot …    [impots]
    2026-08-29 ±3j    2450.00  →    2432.55   Salaire …

  ⚠ passe sous 300 € le 2026-08-25 (-17.45 €), poussé par « Dgfip Impot Revenu »
    (1 motif(s) incertain(s) non comptés — la vraie trajectoire peut être plus basse)

Аренда всё ещё оставляет выше минимума; это налоги опускают ниже, за пять дней до зарплаты. Твой банк скажет это утром 25-го. И последняя строка самая важная: земельный налог проходил в истории только дважды, поэтому ему не верят, поэтому он не учитывается — и прогноз сам объявляет, что он оптимистичен, а не притворяется.

Установить или нет

Три способа, в порядке требуемых усилий:

git clone https://github.com/Beennnn/openbanking-mcp && cd openbanking-mcp && ./bankread doctor
uvx --from git+https://github.com/Beennnn/openbanking-mcp bankread doctor   # sans rien installer
pipx install git+https://github.com/Beennnn/openbanking-mcp                 # à demeure

Клонирование в первую очередь, и не по привычке: инструмент, который читает банковские счета, нужно прочитать перед установкой. ./bankread работает из клона, вообще ничего не устанавливая.

Затем, по порядку

# 0. créer l'application chez le fournisseur : https://enablebanking.com/sign-in/
#    Control Panel → API applications → environnement « Production », clé générée.
#    L'URL de retour à déclarer est http://127.0.0.1:8788/callback (à l'identique).

# 1. les deux identifiants (le second est le CHEMIN du .pem téléchargé)
bankread secrets --set          # ils vont dans le trousseau, pas sur le disque

# 2. trouver sa banque, puis signer le consentement (ouvre le site de la banque)
bankread banks bourso           # relève le NOM EXACT que renvoie l'API
bankread link "BoursoBank"      # puis, séparément :
bankread link "Caisse d'Epargne"

# 3. vérifier
bankread doctor
bankread project --days 45 --floor 300

# 4. le brief de 7 h 30 → tâches Todoist
launchd/install.sh
launchctl kickstart -k "gui/$(id -u)/com.bankread.brief-quotidien"   # essai immédiat

Случай BoursoBank конкретно

Это банк, против которого написан этот репозиторий, поэтому вот чего ожидать, а не обобщение. Другой банк поведёт себя иначе — и именно bankread banks является источником истины, а не этот файл:

• ~90 дней истории, не больше. ЕЖЕМЕСЯЧНЫЕ платежи — аренда, EDF, ежемесячные налоги — выявляются с первого чтения: достаточно трёх проходов. Годовые ждут, пока реестр накопит (см. выше).

• Подтверждение проходит через приложение BoursoBank (сильная аутентификация DSP2). Процесс bankread link открывает сайт, затем звонит телефон. Поэтому нужно иметь его под рукой и повторять это действие каждые 90 дней.

• Не рассчитывайте на агрегацию Wicount 360. BoursoBank уже агрегирует счёт Caisse d'Épargne и отправляет по нему оповещения, но DSP2 даёт доступ к счетам, которые ведёт опрашиваемый банк, а не к тому, что он агрегирует извне. Поэтому счёт Caisse d'Épargne требует собственного bankread link с собственным согласием на 90 дней. (Подтвердить при первом подключении: если внешние счета появятся в процессе, тем лучше.)

• Совместные счета выбираются на экране согласия банка. Отмечайте только то, что действительно хотите читать: отмеченное попадает в локальный реестр, а реестр не забывается.

bankread banks bourso даёт точное имя — в Enable Banking банк обозначается по ИМЕНИ и стране, а не по техническому идентификатору — и максимальную длительность согласия, которую предоставляет этот банк. Именно это значение является источником истины, а не этот файл.

link автоматически переходит к загрузке золотого окна: полная история предоставляется только в течение часа после подписания, затем банк возвращается к 90 скользящим дням. Не прерывайте этот шаг — он повторится только при следующем продлении, через три-шесть месяцев.

Команды

Коды выхода: 0 — всё в порядке, 1 — есть на что посмотреть, 2 — жёсткий сбой — чтобы launchd и вызывающие скрипты могли ориентироваться.

Заставить ИИ читать счета

claude mcp add bankread -s user -- "$PWD/bankread" mcp

Или вообще без клонирования, как распространяется любой MCP-сервер:

{
  "mcpServers": {
    "bankread": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Beennnn/openbanking-mcp", "bankread", "mcp"]
    }
  }
}

MCP — открытый протокол, и bankreadlib/mcp.py — это JSON-RPC, написанный вручную: никаких библиотек от издателя, никаких токенов, никаких исходящих вызовов. Тот же сервер объявляется так же в других MCP-клиентах, а bankread json обслуживает тех, кто не является MCP. Всё — включая то, как полностью обойтись без него — в docs/integration.md.

Два ограничения, оплаченных заранее, которые не стоит переоткрывать

Четыре вызова в день на счёт. Большинство банков ограничивают четырьмя вызовами на счёт в день фоновую загрузку. Четыре. Это не предел, к которому приближаются, это предел, который достигается за одно утро отладки. Отсюда кэш, который не является удобством: без него утренняя сводка сбоит через день. Отсюда также --refresh, который явный и никогда не используется по умолчанию.

Потолок снимается, когда пользователь действительно находится перед экраном, что банку сообщает заголовок PSU. bankread отправляет его только если команда имеет терминал: у сводки в 7:30 его нет, поэтому она остаётся ограниченной. Это заявление банку, а не настройка производительности — установить его в «истина» из агента launchd было бы ложью.

Короткая история делает прогноз ОПТИМИСТИЧНЫМ, а не неполным. Не все банки предоставляют тринадцать месяцев — BoursoBank предоставляет около 90 дней. При менее чем 380 днях годовой платёж (земельный налог, страховка, сбор) не мог быть замечен дважды, поэтому он не существует для детектора, и объявленная траектория лучше реальной. Это единственное место, где ошибка стоит денег, поэтому upcoming, project и doctor говорят об этом прямо.

И главное, именно поэтому ledger.py накапливает, а не кэширует. Первый вариант (2026-08-20, утро) хранил мгновенный снимок: каждое чтение заменяло предыдущее. При банке с 90 днями это делало годовой платёж не «ещё не обнаруженным», а необнаружимым навсегда — всё, что выходило за квартал, исчезало из API и из кэша одновременно. Регистр вплавляет каждое чтение в долговечный файл; через год брифингов bankread знает 365 дней там, где банк показывает только 90, и налог на недвижимость появляется при втором прохождении. bankread doctor показывает обратный отсчёт.

Правило вклада, применённое к остатку

Ни одной зелёной строки, которая не была бы наблюдена.

Любой ответ read.py несёт поле etat:

Никогда голого остатка. solde: null, etat: "inconnu" это не нулевой счёт, и это худшее возможное прочтение отсутствующего числа — описания инструментов MCP повторяют это модели перед вызовом, чтобы она не усваивала это на своих ошибках.

Та же дисциплина в прогнозах: срок, увиденный дважды, — не срок, а совпадение. Он выходит с пометкой confidence: "faible" и не попадает в проекцию. Три регулярных прохождения — факт.

И о поступлениях: проекция только расходов даёт траекторию, которая всегда падает, а значит, тревогу каждый день, а через неделю — никакой тревоги вовсе. Зарплата и пособия обнаруживаются тем же путём и учитываются в другую сторону. test_le_salaire_qui_arrive_avant_evite_la_fausse_alerte сохраняет этот случай.

Брифинг в 7:30

brief/brief.md — это текст, который Claude выполняет каждое утро, запускаемый через launchd посредством brief/run-brief. Он читает Gmail и банк, и его единственный полезный выход — небольшое число задач Todoist с меткой auto-brief.

Тишина — это успех. Утро без поводов для сообщения даёт ноль задач — ни ежедневной сводки, ни «нечего сообщать». Только пять поводов создают задачу, а журнал ~/.config/bankread/brief-vu.json не даёт одной и той же задержанной посылке порождать по задаче в день в течение двух недель.

run-brief передаёт ЗАКРЫТЫЙ список инструментов в claude --allowedTools. Ни одного инструмента записи Gmail там нет: брифинг читает почту, но никогда не отвечает. И ничего не оставлено на запрос разрешения, ведь в 7:30 перед экраном никого нет.

Вызываемая модель — это сменный драйвер (brief/agents/), а не жёстко прописанный вызов: BANKREAD_AGENT=aucun brief/run-brief запускает брифинг вообще без ИИ, и проекция всё равно попадает в журнал. Чтение счетов никогда не требовало модели — см. docs/integration.md.

launchd/install.sh устанавливает только этого агента. Установочный скрипт, который делает больше, чем его название, в итоге переустанавливает что-то мёртвое, и мы проводим вечер в поисках того, почему работают два экземпляра.

Смена провайдера

Связность тонкая, и это проверяется тестом (test_le_contrat_tient_en_deux_methodes):

Чтобы подключить третьего провайдера, достаточно модуля, который предоставляет эти два метода — Protocol из provider.py объявляет их, а provider.charger() делает выбор:

balances(account_id)                          -> {"balances": [...]}
transactions(account_id, date_from, date_to)  -> {"transactions": {"booked": [...]}}

Ожидаемый формат — это формат Берлинской группы: balanceType / balanceAmount для остатков, bookingDate и transactionAmount со знаком для операций. Если провайдер говорит на другом языке, перевод оплачивается в его клиенте и нигде больше — см. enablebanking._operation(), который возвращает знак суммам, которые Enable Banking всегда отдаёт положительными.

Три ловушки, встреченные при написании клиента Enable Banking, которые не стоит переоткрывать:

• знак сумм хранится рядом с суммой (credit_debit_indicator), а не внутри неё. Если скопировать его как есть, каждое списание будет засчитано как поступление;

• полная история живёт всего час после подписания (см. выше);

• предоставленная длительность согласия может быть короче запрошенной: сохраняется ответ банка, иначе doctor объявляет согласие действительным через два месяца после его смерти.

Тесты

python3 test_bankread.py

51 тест, только стандартная библиотека, никакой сети. Они проверяют прежде всего случаи, когда код должен молчать: два вхождения не делают регулярный платёж, кэш тридцати часов — уже не остаток, проекция не строится на никогда не наблюдавшемся остатке. Детекция, ошибающаяся в дате, не падает — она объявляет налоги 12-го вместо 15-го с той же уверенностью.

Что не версионируется

~/.config/bankread/state.json (связанные счета, токены, даты согласий) и ~/.cache/bankread/ — специфичны для этой машины и этого согласия. Учётные данные провайдера нигде на диске не лежат: они в связке ключей macOS, сервис bankread-enablebanking (или bankread-gocardless), включая закрытый ключ RSA.

⚠️ ~/.local/share/bankread/ledger/ — отдельно: это регистр, и он не очищается. То, что в нём есть, банк уже не сможет выдать снова — за пределами 90 дней он забыл. Удалить его вместе с кэшем — значит вернуться к трём месяцам памяти. Он хранится в данных, а не в кэше, именно чтобы затруднить эту путаницу. Осознанная плата: год банковских операций в открытом виде на диске, с правами 0600.