openbanking-mcp — 读取账户，并提前预警

仓库名为 openbanking-mcp，命令名为 bankread。 这不是疏忽：仓库名说明它是什么——一个构建在 Open Banking 之上的 MCP 服务器——因为这是人们找到它的方式。命令名说明它的用途，而 bankread doctor 比 openbanking-mcp doctor 更好输入。配置路径（~/.config/bankread、钥匙串 bankread-enablebanking）跟随命令名，而非仓库名。

通过 DSP2（AIS 牌照）只读银行账户，外加每日简报发送到 Todoist。Python 3.11+，零第三方依赖：HTTP 用 urllib，MCP 服务器的 JSON-RPC 手写实现。运行在 Mac 上，不在云端。

⚠ 数据提供商需要自行选择——开始前请先阅读

本仓库最初使用 GoCardless Bank Account Data（前 Nordigen）客户端，这曾是明显的免费途径。2026-08-20 核实：该服务已停止新用户注册，并正在逐步关停。因此 bankreadlib/gocardless.py 仅对已有账户的人有用。

个人使用的免费替代方案是 Enable Banking，其 Restricted Production 层级提供真实的生产数据，仅限自己关联的账户——这正是本项目的用途，且无需支付许可费。Enable Banking 客户端已编写完成（bankreadlib/enablebanking.py）：通过电子邮件自助注册，使用 RS256 签名的 JWT 进行认证——无需依赖，标准库即可（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 钥匙串中，而非文件中——文件最终会进入备份压缩包、一次不小心的 cat、一次同步到 NAS 的 rsync。对于 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 和调用脚本识别。

让 AI 读取账户

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 代理将其设为"true"将是谎言。

短历史记录使预测偏于乐观，而非不完整。 并非所有银行都提供十三个月——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 和银行，唯一有用的输出是少量标记为 auto-brief 的 Todoist 任务。

沉默即是成功。 一个无事可报的早晨产生零任务 —— 没有每日摘要，没有「无事可报」。只有五种情况会创建任务，而 ~/.config/bankread/brief-vu.json 记录文件防止同一个延迟包裹在两周内每天生成一条任务。

run-brief 向 claude --allowedTools 传递一个封闭的工具列表。其中没有任何 Gmail 写入工具：简报只读邮件，绝不回复。而且没有任何内容留给授权请求，因为 7 点 30 分没有人坐在屏幕前应答。

调用的模型是一个 可替换的驱动程序（brief/agents/），不是硬编码调用：BANKREAD_AGENT=aucun brief/run-brief 让简报在完全没有 AI 的情况下运行，预测仍然落入日志。账户读取从来不需要模型 —— 参见 docs/integration.md。

launchd/install.sh 只安装这一个代理。一个做得比名字更多的安装脚本最终会重新安装一个已死的东西，然后整个晚上都在找为什么有两个副本在运行。

更换供应商

耦合很薄，并且由一个测试验证（test_le_contrat_tient_en_deux_methodes）：

要接入第三个供应商，只需一个暴露这两个方法的模块 —— provider.py 中的 Protocol 声明它们，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。