FinLedger

一个本地财务账本，提供三种读取视图，外加一个 MCP 服务器，让智能体可以查询它们：

• expenses：支出账户，与对等方报销对账

• investments：券商余额、持仓和交易活动

• income：工资单（毛收入、预扣、实发工资）

支出和投资仅共享同一个存储，别无其它。每个账户都带有显式的 domain，每条支出查询都通过它进行连接，因此股票买入不会进入报销匹配器。

匹配器以规则为先。不确定时它会弃权。在匹配结果减少净支出之前，需要人工或智能体确认。

真实交易、工资单和 API 密钥都留在你的机器上（~/.finledger/ledger.db、.env）。本仓库仅附带代码和一套合成评估集。

安装

需要 Python 3.10+。账本、匹配器、MCP 循环和评估框架均只使用标准库。pypdf 是可选的，仅在导入工资单 PDF 时需要。

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

MCP 服务器

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18 个工具，命名空间为 expenses_*、investments_* 和 income_*，另有 savings_rate、accounts、sync 和 reconcile。

Cursor 示例（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

默认账本路径为 ~/.finledger/ledger.db。

命令行接口

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve 会在 :8770 打开一个本地工作台。在 macOS 上，你也可以双击 scripts/Expense Desk.command。

可选实时数据源（将凭证放入 .env，切勿提交它）：

将 .env.example 复制为 .env。

公开评测

已发布的金标准数据集是合成的。它由 scripts/make_sample_data.py 生成，存放在 data-sample/ 中。每个交易行都标记为 synthetic: true。它是针对匹配器行为的覆盖集（干净匹配、扇入、捆绑、对等方转出父交易、商户退款、弱备注、跨来源孪生）。它不是匿名化的真实数据。

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

可从本仓库复现的数字

在 data-sample/ 上使用 rules_v0 测得（窗口 ±90 天，自动匹配阈值 0.75）：

重新运行 python3 scripts/eval_public.py 即可刷新这些指标。样本上剩余的两个误报是匹配器真正的弱点，包括 emoji 召回提升规则的过度适用。

本仓库未包含的内容

开发过程中使用了一个约含 92 个标注示例的私有金标准数据集。它包含真实人名和真实消费记录，且未公开发布。不要将样本数字视为该数据集的复现。语料不同、规模不同、分数不同。

本仓库不声称 100% 的自动匹配精确率。

匹配器

参见 reconcile/README.md。简版如下：

使用 python3 labeling/app.py 为样本语料标注（默认使用 data-sample/）。

许可证

MIT