Finance Manager MCP

MCPクライアント向けのセルフホスト型パーソナルファイナンス。銀行は読み取り専用のまま（SimpleFIN）で、データはあなたが所有するローカルSQLiteファイルに保存されます。LLMは決定的な合計値のみを照会でき、台帳に書き込むことは一切ありません。

SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

この構成の理由

• 冪等な取り込み — トランザクションは銀行が割り当てた SimpleFIN id をキーにしています。同じダンプを再同期しても正味の新規行はゼロで、同じ外見の新しい取引が誤ってまとめられることはありません。

• 決定的な分類 — 最初に一致したルールを採用する正規表現ベースです。書き込み経路にモデルは含まれません。

• ウォームキャッシュ — 月間支出、キャッシュフロー、純資産スナップショット、定期入出金がSQLiteに保存されるため、再起動してもすぐに利用できます。キャッシュは派生データであり、rebuild-cache が元テーブルから再生成します。

• プロファイルUUID名前空間 — すべての書き込みツールが profile_id を必須とします。複数のプロファイルが互いに漏れ合うことはありません。

• デュアルトランスポート — Claude Desktop / Cursor 向けのstdio と、兄弟パッケージ GRPC-MCP による gRPC に対応しています。

Related MCP server: personal-finance-mcp

セットアップ

Python 3.11+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix:    source .venv/bin/activate
pip install -e ".[dev]"
# optional gRPC transport (sibling ../GRPC-MCP)
pip install -e "../GRPC-MCP/python"
pip install -e ".[grpc]"

cp .env.example .env
# paste a Fernet key into FINANCE_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

finance-mcp init                          # creates data/finance.db + a default profile
finance-mcp profile list                  # copy the profile UUID

SimpleFIN に接続する

MCPクライアントから銀行への接続を依頼します。エージェントは次の手順を実行します：

1. begin_simplefin_connect を呼び出します（またはプロンプト connect_simplefin を使用します）。

2. bridge.simplefin.org を表示します — サインインして銀行（読み取り専用）を接続し、一度だけ使えるセットアップトークンをコピーします。

3. そのトークンを使って claim_connection を呼び出します。アクセスURLは保存時に暗号化されます。

4. 任意で、同じ profile_id に対して sync_now を実行します。

ターミナルを希望する場合はCLIも引き続き使用できます。

finance-mcp claim-token --token "<setup-token>" --name "My Banks" --profile <PROFILE_UUID>
finance-mcp sync --profile <PROFILE_UUID>

sync はTask Scheduler / cron から実行しても安全です。実行時間が重なっても二重にカウントされることはありません。

サーバーを起動する

finance-mcp serve-stdio                   # Claude Desktop / Cursor
finance-mcp serve-grpc --auth bearer      # sibling GRPC-MCP transport
finance-mcp token new --name cursor --profile <PROFILE_UUID>

ベアラートークンは一度だけ表示されます。gRPCはSHA-256ハッシュのみを保存します。

アトミック関数

finance_mcp.api 内はすべて素の関数です。MCPツールは薄いラッパーにすぎません。サーバーを起動せずにライブラリをインポートできます：

from finance_mcp.config import Settings
from finance_mcp.core.db import Database
from finance_mcp import api

db = Database.from_settings(Settings.from_env())
print(api.net_worth(db, profile_id))

読み取り

list_accounts, get_balances, net_worth, net_worth_history, search_transactions, recent_transactions, spending_by_category, cash_flow, recurring_streams, upcoming_payments, budget_status, list_rules, sync_status, profile_info, list_profiles, begin_simplefin_connect

書き込み（常に profile_id が必要）

claim_connection, create_rule, update_rule, delete_rule, apply_rules, create_budget, update_budget, delete_budget, sync_now

テスト

テストスイートは自己完結型です — 合成フィクスチャのみで、認証情報は不要です。

pytest -q

セキュリティ

• SimpleFINのアクセスURLは FINANCE_ENCRYPTION_KEY（Fernet）で暗号化されます。キーを忘れずにバックアップしてください。

• gRPCのベアラートークンはハッシュとして保存されます。

• 読み取りツールは mode=ro でSQLiteを開きます。書き込みツールは唯一の変更経路であり、プロファイル単位でスコープされます。

• data/ と .env はgitignoreされています。

ライセンス

自分でホストする個人ファイナンスの用途なら、自由に使ってください。