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 会通过原始数据表重建。

• Profile UUID 命名空间 —— 每个写入工具都要求 profile_id。多个配置文件之间不会相互泄漏。

• 双传输方式 —— 通过 stdio 连接 Claude Desktop / Cursor，通过 gRPC 连接配套的 GRPC-MCP 包。

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 上执行 move 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>

Bearer 令牌只打印一次。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

测试

测试套件是封闭的（hermetic）——只用合成测试夹具（fixtures），无凭据即运行。

pytest -q

安全

• SimpleFIN 的访问 URL 用 FINANCE_ENCRYPTION_KEY（Fernet）加密。请备份该密钥。

• gRPC 的 Bearer 令牌只存储为哈希。

• 读取工具以 mode=ro 打开 SQLite。写入工具是唯一的变更路径，并且受配置文件作用域限制。

• data/ 与 .env 已在 .gitignore 中。

许可证

你可以自由使用，适用于个人自托管财务管理。