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 に実用的なソリューションの一巡と、コードを変えた3つの発見は docs/fournisseurs.md にある。

誰にも代わりにできないことが一つ残っている：Enable Banking アカウントを作成し、そこに銀行口座を申告し、同意に署名すること。 アプリケーションIDと秘密鍵は個人のものだ — 共有するものは何もなく、そこから始める必要がある。

リポジトリの他のすべてはプロバイダーに依存しない。

解決する問題と、解決しない問題

BoursoBank はすでに「残高が少なくなっています」を送る。Caisse d'Épargne はすでに「入金がありました」を送る。Amazon は「配送中です」、Leboncoin は「出品者が確認しました」を送る。情報はすでに届いている — ただ遅すぎて、間違った場所に届くだけだ。

• 遅すぎる：閾値アラートは引き落としの後に発動する。15日の朝、税金は引き落とされ、残高は少なく、アラートはそれを確認するだけだ；

• 間違った場所：読まれていないものが多い200通のメールの真ん中。

したがって、このリポジトリは不足している情報を探しに行くわけではない。誰もやらない唯一のことをやる：引き算だ。今日の残高から、月末までに落ちるものを引く。銀行も税務署もそれをできない — どちらも相手が見えないからだ。

解決しない問題：ここにあるものは、自分の口座を確認することを代替しない。新しい、見たことのない引き落としは、周期性検出器には見えない。

Related MCP server: bank.mcp

読み取り専用、そして礼儀のためではない

接続はプロバイダー（Enable Banking、無料ティア Restricted Production）の DSP2 / AIS 認可を通る。AIS とは口座情報の集約だ。支払い開始は別の認可（PIS）であり、このトークンはそれを持たず、銀行もそれを開かない。漏洩の最悪のシナリオは履歴の読み取りであり、資金の移動ではない。 これがこのリポジトリが存在することを許される唯一の理由だ。

実用的な帰結が3つ：

• プロバイダーの認証情報はmacOS キーチェーンに置かれ、ファイルには置かれない — ファイルはバックアップの tar や、うっかりした cat、NAS への rsync に紛れ込む。Enable Banking の場合、これには RSA 秘密鍵も含まれる：bankread secrets --set がそれを読み取り、保管し、ダウンロードした .pem を削除するよう促す；

• 銀行の同意は期限切れになる — 銀行が与えるものに応じて3〜6ヶ月、そして記録されるのは私たちの要求ではなく銀行の回答だ。誰もあなたの代わりにそれを更新できない：自分の銀行のサイトに戻る必要がある。doctor は J-14 に警告する（J-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)

家賃はまだ下限を上回っている；税金がそれを下回らせる、給料の5日前に。あなたの銀行は25日の朝にそれを言うだろう。そして最後の行が最も重要だ：固定資産税は履歴に2回しか通っていないので、信頼されず、したがってカウントされない — そして予測は、見せかけをする代わりに、自分が楽観的であると自ら宣言する。

インストールするか、しないか

3つの方法、要求するコミットメントの順に：

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、税金の月割り — は最初の読み取りで出てくる：3回の通過で十分だ。年次のはレジスタが蓄積するのを待つ（上記参照）。

• 検証は BoursoBank アプリを通る（DSP2 強認証）。bankread link の流れはサイトを開き、その後電話が鳴る。したがって手元に用意し、この操作を90日ごとにやり直す必要がある。

• Wicount 360 の集約に頼らないこと。 BoursoBank はすでに Caisse d'Épargne の口座を集約し、それについてアラートを送るが、DSP2 は照会された銀行が保有する口座へのアクセスを与えるのであって、他から集約したものではない。したがって Caisse d'Épargne の口座は、独自の90日間の同意を持つ、独自の bankread link を必要とする。（最初の接続時に確認すべき：外部口座がフローに現れるなら、なお良い。）

• 共同口座は銀行の同意画面で選択する。本当に読みたいものだけにチェックを入れる：チェックしたものはローカルレジスタに入り、レジスタは忘れない。

bankread banks bourso は正確な名前を与える — Enable Banking では銀行は技術的IDではなく、その名前と国で指定される — そしてその銀行が与える最大同意期間を与える。最終的な判断はこのファイルではなく、その値だ。

link は自動的にゴールデンウィンドウの取得に進む：完全な履歴は署名後1時間以内にのみ提供され、その後銀行は90日のスライディングに戻る。このステップを中断しないこと — それは次の更新、3〜6ヶ月後まで再実行されない。

コマンド

終了コード：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 にある。

先に支払われた2つの制限、再発見しないこと

口座ごとに1日4回の呼び出し。 ほとんどの銀行は、バックグラウンドで行われる取得を口座ごとに1日4回に制限している。4回。これはかろうじて触れる限界ではなく、デバッグの午前中に到達する限界だ。したがってキャッシュは快適さではなく必須だ：それなしでは、朝のブリーフは2日に1回失敗する。したがって --refresh もあり、それは明示的であり、決してデフォルトではない。

上限は、ユーザーが実際に画面の前にいるときに解除される。これは PSU ヘッダーが銀行に宣言するものだ。bankread はコマンドがターミナルを持つ場合にのみそれを送る：朝7時30分のブリーフはターミナルを持たないので、制限されたままになる。これは銀行への宣言であり、パフォーマンス設定ではない — launchd エージェントから「真」に設定することは嘘になる。

短い履歴は予測を楽観的にするのであって、不完全にはしない。 すべての銀行が13ヶ月を返すわけではない — BoursoBank は約90日を返す。 380日未満では、年次の支払い（固定資産税、保険、使用料）は2回通過するのを見られていないため、検出器にとって存在せず、したがって宣言される軌道は実際より良い。間違えるとお金がかかる唯一の場所なので、upcoming、project、doctor はそれを明確に言う。

そして何よりも、それが ledger.py がキャッシュではなく蓄積する理由です。最初の草案（2026-08-20、朝）はスナップショットを保持していました。各読み取りが前のものを置き換えていました。90日間の銀行では、それは年次の期日を「まだ検出されていない」ではなく生涯検出不能にしました。四半期を超えるものはすべてAPIとキャッシュから同時に消えていました。台帳は各読み取りを永続ファイルに溶かし込みます。1年間のブリーフの後、bankreadは銀行が90日しか表示しないところで365日を知っており、固定資産税は2回目の通過で現れます。bankread doctor はカウントダウンを表示します。

預金のルールを残高に適用

観測されていない緑の行はない。

read.py のすべての応答には etat フィールドがあります：

裸の残高は決してありません。solde: null, etat: "inconnu" はゼロ口座ではありません。これは欠落した数字の最悪の読み取り方です。MCPツールの説明は、モデルが呼び出す前にそれを繰り返し、間違えることで学ばないようにします。

予測にも同じ規律があります。2回見た期日は期日ではなく、偶然です。confidence: "faible" とマークされて出力され、予測には入りません。3回の定期的な通過は事実です。

収入についても同様です。支出だけを予測すると常に下落する軌道になり、毎日アラームが出て、1週間後にはアラームがまったく出なくなります。給与と手当は同じ経路で検出され、逆方向に数えられます。test_le_salaire_qui_arrive_avant_evite_la_fausse_alerte がこのケースを守っています。

7時30分のブリーフ

brief/brief.md は、launchdが brief/run-brief を介して起動し、Claudeが毎朝実行するテキストです。Gmailと銀行を読み取り、その唯一の有用な出力は auto-brief とラベル付けされた少数のTodoistタスクです。

沈黙は成功です。 報告することが何もない朝はゼロタスクを生成します。毎日の要約も「報告事項なし」もありません。タスクを作成するのは5つの理由だけで、~/.config/bankread/brief-vu.json というノートは、同じ遅延パッケージが2週間毎日1つ生成するのを防ぎます。

run-brief は claude --allowedTools に閉じたツールリストを渡します。Gmail書き込みツールは含まれていません。ブリーフはメールを読むだけで、決して返信しません。また、7時30分に画面の前に誰もいないため、承認要求に委ねられるものは何もありません。

呼び出されるモデルは交換可能なドライバー（brief/agents/）であり、ハードコードされた呼び出しではありません。BANKREAD_AGENT=aucun brief/run-brief はAIなしでブリーフを実行し、予測はそれでもジャーナルに落ちます。口座の読み取りにモデルは必要ありませんでした — docs/integration.md を参照してください。

launchd/install.sh はこのエージェントだけをインストールします。名前以上のことをするインストールスクリプトは、結局死んだものを再インストールし、2つのコピーが動いている理由を探して夜を過ごすことになります。

プロバイダーの変更

結合は薄く、テスト（test_le_contrat_tient_en_deux_methodes）で検証されています：

3番目のプロバイダーを接続するには、これら2つのメソッドを公開するモジュールだけで十分です。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クライアントを書く際に遭遇した3つの落とし穴、再発見しないためのもの：

• 金額の符号は金額の隣（credit_debit_indicator）にあり、中にはありません。そのままコピーすると、すべての引き落としが収入として数えられます。

• 完全な履歴は署名後1時間しか持続しません（上記参照）。

• 付与された同意の期間は要求されたものより短い場合があります。記録するのは銀行の応答です。そうしないと、doctor は同意が死んでから2ヶ月後に有効と宣言します。

テスト

python3 test_bankread.py

51テスト、標準ライブラリのみ、ネットワークなし。主にコードが沈黙すべきケースを検証しています。2回の出現は期日にならない、30時間のキャッシュはもはや残高ではない、観測されたことのない残高では予測しない。日付を間違える検出はクラッシュしません — 同じ自信を持って15日ではなく12日に税金を発表します。

バージョン管理されていないもの

~/.config/bankread/state.json（リンクされた口座、トークン、同意日）と ~/.cache/bankread/ — このマシンとこの同意に固有のものです。プロバイダーの資格情報はディスク上のどこにもありません。macOSキーチェーン、サービス bankread-enablebanking（または bankread-gocardless）にあり、RSA秘密鍵も含まれます。

⚠️ ~/.local/share/bankread/ledger/ は別です。これは台帳であり、パージされません。 そこに含まれるものは、銀行が再び提供することはできません。90日を超えると、銀行は忘れてしまいます。キャッシュと一緒に削除すると、3ヶ月のメモリからやり直すことになります。この混乱を難しくするために、キャッシュではなくデータに正確に保管されています。受け入れられた代償：ディスク上に0600の権限で1年間の銀行取引が平文で存在します。